Living Documentation (presentation)
May. 30, 2017•0 likes•790 views
Download to read offline
Report
Software
“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.
Matthias NobackFollow
More Related Content
Similar to Living Documentation (presentation)
Open-Source Project Tools for Corporate Projects?Bertrand Delacretaz
Programming Languages #devcon2013Iván Montes
Beer&Tech: Tech Documentation - cod == docGilles Legoux
Atlassian Summit 2012 - Immigration to Confluence: A Journey Through Foreign ...Atlassian
Domain driven design and model driven developmentDmitry Geyzersky
Build your own Language - Why and How?Markus Voelter
More from Matthias Noback
Rector fireside chat - PHPMiNDS meetupMatthias Noback
Service abstractions - Part 1: QueriesMatthias Noback
Hexagonal Symfony - SymfonyCon Amsterdam 2019Matthias Noback
Advanced web application architecture - PHP BarcelonaMatthias Noback
A testing strategy for hexagonal applicationsMatthias Noback
Advanced web application architecture - TalkMatthias Noback
Recently uploaded
LangChain + Docugami WebinarTaqi Jaffri
Alluxio + Eckerson Webinar | Simplifying and Accelerating Data Access for AI/...Alluxio, Inc.
Kontinuierliche Sicherheitstests für APIs mit Testkube und OWASP ZAPQAware GmbH
Database storage engine internals.pptxAdewumiSunkanmi
Top Benefits of Web based Systems. sarasiva4
Kubernetes with Cilium in AWS - Experience Report!QAware GmbH
Living Documentation (presentation)
- 1. Matthias Noback @matthiasnoback Living Documentation
- 2. training.matthiasnoback.nl
- 3. Documentation: Quite an emotional matter Untrustworthy Boring Ugly Failure Loser
- 4. Greek Tragedy Horrible stuff
- 5. Greek Tragedy The Chorus
- 6. Masks for the Chorus Exaggerated, non- individualised emotions
- 7. Catharsis Aristotle
- 9. #NoDocumentation
- 10. A SINGLE MAN
- 11. ReST & Sphinx
- 15. Commit rights for the PM
- 16. The Dreaded Definition of Done
- 17. $ git commit --no-verify
- 19. Emotional stuff! Clean Reliable Fun Good-looking
- 20. What's the problem?
- 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!
- 26. Awesome locations Wiki Confluence Balsamiq Gliffy Word file PDF file
- 30. You're doing it wrong
- 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
- 41. Standards & Conventions
- 42. Ubiquitous Language
- 43. Specifications (for units of code)
- 44. Specifications (for the application as a whole)
- 45. Architecture & design choices Reflected in artefacts
- 48. HOUSE!!!!
- 49. Code Tests Documentation Acceptance criteria
- 50. CodeTestsDocumentation Acceptance criteria
- 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. https://leanpub.com/livingdocumentation Cyrille Martraire
- 53. Vocabulary and pattern language Separate Activities Manual Transcription Redundant Knowledge Information Graveyard Misleading Help ...
- 54. Knowledge Store & Transfer
- 55. Knowledge Generic Specific
- 56. Learn generic knowledge
- 57. Document specific knowledge
- 58. Default: no documentation
- 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."
- 63. Locations... revisited Wiki Confluence Balsamiq Word file PDF file
- 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!
- 68. Annotations @Get @Post @Route
- 69. Annotations @Adapter @Proxy
- 70. Annotations @DataTransferObject @Entity @ValueObject @Immutable
- 71. Annotations @BoundedContext @CoreConcept @Landmark
- 72. Highlight
- 74. Directory/namespace structure src Meetup.com Membership ... Organizing Domain Application Infrastructure Persistence MySQL Redis Applications Bounded contexts Layers Ports Adapters
- 76. Refactorable The documentation is (near) the code
- 77. Up-to-date No manual transcription or reconciliation needed
- 78. Fun factor Automated, good-looking
- 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
- 84. Clean Reliable Fun Good-looking Thanks for attending! Exciting