Living Documentation (presentation)
“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.
Living Documentation (presentation)
- 3. Documentation: Quite an emotional matter Untrustworthy Boring Ugly Failure Loser
- 6. Masks for the Chorus Exaggerated, non- individualised emotions
- 10. A SINGLE MAN
- 11. ReST & Sphinx
- 15. Commit rights for the PM
- 16. The Dreaded Definition of Done
- 17. $ git commit --no-verify
- 21. To write code We love it
- 22. Process 1. Write code 2. Write docs
- 23. Process 1. Write code 2. Write tests Provide separate estimations Skip if deadline is near
- 24. Process 1. Write tests 2. Write code TDD! TDD! TDD!
- 25. Process 1. Write docs 2. Write code DDD! DDD! DDD!
- 33. Why bad? • Requires manual transcription • No reconciliation mechanism • Hard to refactor • Impossible to diff • (Hard to copy-paste)
- 34. The only proper location Inside your project's source code repository Code changes /w documentation changes History & versioning No rights mgmt
- 35. Wait a minute Code changes /w documentation changes
- 38. Self-documenting code Code that doesn't need comments documentation
- 40. Meaningful names
- 43. Specifications (for units of code)
- 44. Specifications (for the application as a whole)
- 45. Architecture & design choices Reflected in artefacts
- 48. HOUSE!!!!
- 51. 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
- 53. Vocabulary and pattern language Separate Activities Manual Transcription Redundant Knowledge Information Graveyard Misleading Help ...
- 59. 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.
- 60. "Each instruction typed in a programming language is a decision."
- 61. "In a software project most of the knowledge is present in some form somewhere in the artefacts."
- 62. "The best place to store documentation is on the documented thing itself."
- 64. The Ultimate Location Stakeholder- oriented auto-built documentation website Read-only Always up-to-date Windows XP-friendly Complete Good-looking External
- 65. Ideas
- 66. Readable specifications testCollect() becomes it_collects_directories_directly_under_source_roots()
- 67. Specifications Feature: In order to ... As a ... I want to be able to ... Scenario: Given ... When ... Then ... Documentation! Reconciliation mechanism!
- 72. Highlight
- 76. Refactorable The documentation is (near) the code
- 77. Up-to-date No manual transcription or reconciliation needed
- 79. "If it’s not fun, you’ll not want to do it so often and the practice will progressively disappear."
- 80. Insightful Feedback on design, UL, etc.
- 81. Principles of Living Documentation 1. Reliable 2. Low-Effort 3. ...
- 82. 3. Collaborative
- 83. 4. Insightful