Technical documentation is a backup (so make sure it works)

Imagine working on a team of programmers who write perfect code, never forget anything, never leave the team, have perfect verbal communication skills, and love meetings. That would be weird on many levels, but at least then you’d have a chance of not needing any technical documentation. The rest of us, who have legacy code to deal with, need to know how to write useful documentation. Otherwise, other peoples’ code will become a single point of failure to understand what’s going on.

Technical documentation is our backup for not being able to understand a system and its code by looking at it. Unfortunately, these backups probably haven’t been tested recently and don’t actually work. The solution is to write less documentation, not more, but also not none. By writing less documentation, you can focus on writing documentation that counts, actually maintaining what you write, and have more time left over for writing code.

Transcript

1. @PeterHilton http://hilton.org.uk/ Technical documentation is a back-up (so make sure it works)
3. Sergio Souza
4. Ramon Cordeiro
5. Three kinds of legacy code Good code but… old technology Code written by… someone else (a.k.a. bad code) Complex code because of… 10 years’ built-up business rules 6 @PeterHilton •
6. Three kinds of technical documentation Extensive tech documentation. Quality system records, e.g. code review forms No documentation at all. None. (not even code comments ) Minimal docs: data dictionary, operations guides (and code comments ) 7 @PeterHilton •
7. Three lessons learned Generous budget Documentation was a backup Bad code, original team not available No backup was a problem. Planning for maintainability Minimum viable docs FTW! 8 @PeterHilton •
8. Lessons learned
9. We don’t like software documentation when it’s: 1. Time-consuming 2. Hard 3. Wrong 4. Messy 5. Too long 6. Missing 7. Unversioned 8. Incomplete 9. Neglected 10. Boring 10 @PeterHilton • Technical documentation has many failure modes … but no automated tests.
10. ‘There is no documentation fairy’ Allan Kelly Anthony Tran
11. Technical design docs don’t help maintainers 12 @PeterHilton • Software design (a.k.a. development) ‘Technical specifications’ = design choices and plans Maintenance (a.k.a. development) ? ? ? = how to understand and modify the code
12. Three rules for backups Rule 1 You need backups for important things (things go wrong) Rule 2 Not using backups regularly might be a sign that things are going well (but also a risk) Rule 3 If you haven’t tested your backups then they don’t work (things go wrong) 13 @PeterHilton •
13. Three rules for documenting legacy systems 14 @PeterHilton • I had to invent a word for legacy systems…
15. Three rules for documenting legacy systems Rule 1 Bad code: needs all the docs you can get (like clues in a murder mystery) Rule 2 There’s always too much code (so focus on getting started) Rule 3 Some legacy systems are undocumentable (document the process instead) 16 @PeterHilton •
16. How to cheat at docs
17. How far will you go? Chris Moore
18. How far will you go? You don’t have to write docs if you leave your mobile phone number in every source file. 19 @PeterHilton •
19. Improve the code instead Better naming and cleaner code (fewer code comments) ⚙ Automated builds (shorter installation instructions) Standard architectures (no system diagrams) 20 @PeterHilton •
20. The ideal documentation system 1. Works with your favourite IDE 2. Integrated with source code 3. Structured content 4. Version control 5. Minimal dependencies 6. Doesn’t require writing one yourself when you should be working 21 @PeterHilton •
21. Dejdżer / Digga / CC BY-SA 2.0
22. Code comments Comments feature in almost all programming languages, but remain an almost taboo topic. Developers will go to bizarre lengths to avoid comments and usually fail to write code so good they don’t need any. Comments are not the enemy: meetings are the enemy! 23 @PeterHilton •
23. How to write good code comments 1. Try to write good code first. 2. Write a one-sentence comment. 3. Refactor the code (make it easier to understand). 4. Delete unnecessary comments. 5. Rewrite bad comments (all good writing requires rewriting) 6. Add detail where needed. 7. GOTO 1 24 @PeterHilton •
24. M A N N I N G Peter Hilton Erik Bakker Francisco Canedo FOREWORD BY James Ward Covers Play 2 Play for Scala (Manning, 2014) Peter Hilton Erik Bakker Francisco Canedo http://bit.ly/playscala2p
25. OPD OTHER PEOPLE’S DOCUMENTATION
27. Use standards and frameworks Standards/dictionaries are other peoples’ documentation. Frameworks are other people’s code and the successful ones have good documentation. Not a perfect solution, because standards and frameworks are dependencies that you might not want. 28 @PeterHilton •
28. MVD MINIMUM VIABLE DOCUMENTATION
29. README.md The minimal system is a README per component, the short version of complete system documentation: 30 @PeterHilton • 1. What it is 2. Purpose 3. Features 4. Usage/examples 5. Installation 6. Asking questions 7. Building from source 8. Authors/maintainers 9. How it works 10. Who it’s for
30. Special-purpose documentation for specific needs There are many kinds of documentation that you usually don’t need. But sometimes you do. 31 @PeterHilton • API reference Architecture diagram Contributor’s guide UML diagram Component inventory Entity relationship diagram Data dictionary Process model Business rules Architecture Decision Record
31. You X Ventures Hire technical writers
32. Docs as Code (Eric Holscher) 1. Use the same tools for docs that you use for code: issue tracker, version control, mark-up, review, tests, etc. 2. Use the development team’s workflows. 3. Integrate docs development with the product team. 4. Adopt shared ownership of documentation. 5. Allow any team member to write the first draft. (Relevant for user documentation as well as system docs) http://www.writethedocs.org/guide/docs-as-code/ 33 @PeterHilton •
33. Documentation techniques wish list
34. Architecture Decision Records (Michael Nygard) 1. Concisely record each architecturally significant decision. 2. Use sequential numbering and consistent titles, e.g. ‘ADR 1: Deployment on Ruby on Rails 3.0.10’ 3. Document context, decision, status, and consequences. 4. Write-once: add new records to replace old ones. 5. Read all records to ‘load’ the current state (it’s like event sourcing for documentation) http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions 35 @PeterHilton •
35. Four kinds of documentation (Daniele Procida) ‘There isn’t one thing called documentation, there are four’ 1. Tutorials 2. How-to guides 3. Explanation 4. Technical reference ‘… each of these kinds of documentation has only one job’ (it’s like design patterns for documentation) https://www.divio.com/blog/documentation/ 36 @PeterHilton •
36. A manifesto for error reporting (David R. MacIver) ‘a manifesto for how errors should be reported by software to technical people whose responsibility it is to work with said software’ https://www.drmaciver.com/2013/03/a-rewritten-manifesto-for-error-reporting/ 37 @PeterHilton •
37. Summary
38. Technical documentation 1. Technical documentation is a backup for knowledge (and the rules for backups apply) 2. We need technical system documentation, (but we don’t usually need very much) 3. There are many new practices to replace old approaches; these practices have principles in common. 39 @PeterHilton •
39. Technical documentation Technical documentation is a backup for the team’s knowledge (and the rules for backups apply) For maintenance, we need technical system documentation (but we usually don’t need very much) There are many new practices to replace old approaches (these practices have principles in common) 40 @PeterHilton •
40. @PeterHilton http://hilton.org.uk/ How to write maintainable code (training course) Documentation for developers (training course) more like this…