Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Living Documentation (presentation)

327 views

Published on

“Documentation”, a word that makes developers yawn. It’s what you write because you have to. Documentation is a failure by definition. You know it, it’s true. Writing it is going to be a tiresome, mindnumbing exercise. Documentation is going to be incomplete, outdated, unreliable and soon to be abandoned anyway. Why would you ever start working on it in the first place?

That’s why we were happy when we discovered the Agile Manifesto, which says: “Working software over comprehensive documentation” That’s a good reason to drop all our documentation efforts, right? Well, no. We shouldn’t quit writing docs. We should simply prevent documentation from being an impediment to other prominent Agile values, like “Responding to change”.

In this talk, I’ll cover the Principles of Living Documentation. I’ll show you many ways to make your documentation activities effortless and more fun. Your docs will never be outdated anymore, everything will be version-controlled, automatically built and ready to share with anyone who’s interested. Any day, any time.

Published in: Software
  • Be the first to comment

Living Documentation (presentation)

  1. 1. Matthias Noback @matthiasnoback Living Documentation
  2. 2. training.matthiasnoback.nl
  3. 3. Documentation: Quite an emotional matter Untrustworthy Boring Ugly Failure Loser
  4. 4. Greek Tragedy Horrible stuff
  5. 5. Greek Tragedy The Chorus
  6. 6. Masks for the Chorus Exaggerated, non- individualised emotions
  7. 7. Catharsis Aristotle
  8. 8. #NoDocumentation
  9. 9. A SINGLE MAN
  10. 10. ReST & Sphinx
  11. 11. Commit rights for the PM
  12. 12. The Dreaded Definition of Done
  13. 13. $ git commit --no-verify
  14. 14. Emotional stuff! Clean Reliable Fun Good-looking
  15. 15. What's the problem?
  16. 16. To write code We love it
  17. 17. Process 1. Write code 2. Write docs
  18. 18. Process 1. Write code 2. Write tests Provide separate estimations Skip if deadline is near
  19. 19. Process 1. Write tests 2. Write code TDD! TDD! TDD!
  20. 20. Process 1. Write docs 2. Write code DDD! DDD! DDD!
  21. 21. Awesome locations Wiki Confluence Balsamiq Gliffy Word file PDF file
  22. 22. You're doing it wrong
  23. 23. Why bad? • Requires manual transcription • No reconciliation mechanism • Hard to refactor • Impossible to diff • (Hard to copy-paste)
  24. 24. The only proper location Inside your project's source code repository Code changes /w documentation changes History & versioning No rights mgmt
  25. 25. Wait a minute Code changes /w documentation changes
  26. 26. Self-documenting code Code that doesn't need comments documentation
  27. 27. Meaningful names
  28. 28. Standards & Conventions
  29. 29. Ubiquitous Language
  30. 30. Specifications (for units of code)
  31. 31. Specifications (for the application as a whole)
  32. 32. Architecture & 
 design choices Reflected in artefacts
  33. 33. HOUSE!!!!
  34. 34. Code Tests Documentation Acceptance criteria
  35. 35. CodeTestsDocumentation Acceptance criteria
  36. 36. What if we... 1. Write code, guided by tests 2. Reflect design and architecture choices in the code 3. Let code and tests be docs themselves
  37. 37. https://leanpub.com/livingdocumentation Cyrille Martraire
  38. 38. Vocabulary and pattern language Separate Activities Manual Transcription Redundant Knowledge Information Graveyard Misleading Help ...
  39. 39. Knowledge Store & Transfer
  40. 40. Knowledge Generic Specific
  41. 41. Learn generic knowledge
  42. 42. Document specific knowledge
  43. 43. Default: no documentation
  44. 44. What needs to be documented? • Knowledge that is of interest for a long period. • Knowledge that is of interest to a large number of people. • Knowledge that is valuable or critical.
  45. 45. "Each instruction typed in a programming language is a decision."
  46. 46. "In a software project most of the knowledge is present in some form somewhere in the artefacts."
  47. 47. "The best place to store documentation is on the documented thing itself."
  48. 48. Locations... revisited Wiki Confluence Balsamiq Word file PDF file
  49. 49. The Ultimate Location Stakeholder- oriented 
 auto-built documentation website Read-only Always up-to-date Windows XP-friendly Complete Good-looking External
  50. 50. Ideas
  51. 51. Readable specifications testCollect() becomes it_collects_directories_directly_under_source_roots()
  52. 52. Specifications Feature: In order to ... As a ... I want to be able to ... Scenario: Given ... When ... Then ... Documentation! Reconciliation mechanism!
  53. 53. Annotations @Get @Post @Route
  54. 54. Annotations @Adapter @Proxy
  55. 55. Annotations @DataTransferObject @Entity @ValueObject @Immutable
  56. 56. Annotations @BoundedContext @CoreConcept @Landmark
  57. 57. Highlight
  58. 58. Directory/namespace structure src Meetup.com Membership ... Organizing Domain Application Infrastructure Persistence MySQL Redis Applications Bounded contexts Layers Ports Adapters
  59. 59. Refactorable The documentation is (near) the code
  60. 60. Up-to-date No manual transcription or reconciliation needed
  61. 61. Fun factor Automated, good-looking
  62. 62. "If it’s not fun, you’ll not want to do it so often and the practice will progressively disappear."
  63. 63. Insightful Feedback on design, UL, etc.
  64. 64. Principles of Living Documentation 1. Reliable 2. Low-Effort 3. ...
  65. 65. 3. Collaborative
  66. 66. 4. Insightful
  67. 67. Clean Reliable Fun Good-looking Thanks for attending! Exciting

×