Downloaded 10 times
Uploaded byMatthias Noback
Living Documentation (presentation)
The document discusses the concept of living documentation in software development, emphasizing the integration of documentation with code to enhance reliability, ease of understanding, and collaborative efforts. It critiques traditional documentation methods for being tedious and prone to errors, advocating instead for self-documenting code and automated documentation generation. Key principles highlighted include the need for documentation to be up-to-date, low-effort, and engaging to ensure continuous use and relevance.
More Related Content
Similar to Living Documentation (presentation)
Living Documentation (presentation)
- 1.
- 2.
- 3. Documentation: Quite an emotionalmatter Untrustworthy Boring Ugly Failure Loser
- 4.
- 5.
- 6. Masks for the Chorus Exaggerated,non- individualised emotions
- 7.
- 9.
- 10.
- 11.
- 15. Commit rights forthe PM
- 16.
- 17. $ git commit--no-verify
- 19.
- 20.
- 21. To write code Welove 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!
- 26.
- 30.
- 33. Why bad? • Requiresmanual transcription • No reconciliation mechanism • Hard to refactor • Impossible to diff • (Hard to copy-paste)
- 34. The only properlocation Inside your project's source code repository Code changes /w documentation changes History & versioning No rights mgmt
- 35. Wait a minute Codechanges /w documentation changes
- 38. Self-documenting code Code thatdoesn't need comments documentation
- 40.
- 41.
- 42.
- 43.
- 44. Specifications (for the applicationas a whole)
- 45. Architecture & designchoices Reflected in artefacts
- 48.
- 49.
- 50.
- 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
- 52.
- 53. Vocabulary and pattern language SeparateActivities Manual Transcription Redundant Knowledge Information Graveyard Misleading Help ...
- 54.
- 55.
- 56.
- 57.
- 58.
- 59. What needs tobe 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 typedin a programming language is a decision."
- 61. "In a softwareproject most of the knowledge is present in some form somewhere in the artefacts."
- 62. "The best placeto store documentation is on the documented thing itself."
- 63.
- 64. The Ultimate Location Stakeholder- oriented auto-built documentation website Read-only Always up-to-date Windows XP-friendly Complete Good-looking External
- 65.
- 66.
- 67. Specifications Feature: In order to... As a ... I want to be able to ... Scenario: Given ... When ... Then ... Documentation! Reconciliation mechanism!
- 68.
- 69.
- 70.
- 71.
- 72.
- 74.
- 76. Refactorable The documentation is(near) the code
- 77. Up-to-date No manual transcriptionor reconciliation needed
- 78.
- 79. "If it’s notfun, 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.
- 83.
- 84.