Voxxed Days Thessaloniki 2016 - Documentation Avoidance
0 likes97 views
The document discusses various tactics for avoiding writing software documentation, including: 1. Using constructive laziness to think about documentation but delay writing it. 2. Using techniques like "just-in-time documentation" to avoid writing documentation upfront by pretending it's stored elsewhere or feigning ignorance. 3. Recognizing that while documentation avoidance has its place, compromises like writing minimal documentation may be necessary to explain code to future team members or users.
Voxxed Days Thessaloniki 2016 - Documentation Avoidance
- 1. @PeterHilton http://hilton.org.uk/ Documentation avoidance for developers How to get away with less documentation and spend more time writing code #WriteTheDocs
- 3. What are the causes of software documentation? @PeterHilton • 3
- 4. Justin Ennis / CC BY 2.0
- 5. ‘M&Ms, managers and meetings’ M&Ms generate demand for software documentation. Meetings are failure demand. http://www.happymelly.com/why-work-does-not-happen-at-work-the-mms/ @PeterHilton • 5
- 6. 6@PeterHilton • Michael Coghlan / CC BY-SA 2.0 Unfamiliar domains
- 8. JamesByrum/CCBY-ND2.0 Homer’s Iliad is now legacy poetry
- 9. Developers look for documentation in legacy system Jean-François Millet 1857 Oil on canvasclassicprogrammerpaintings.com
- 10. Rob Smallshire - http://sixty-north.com/blog/predictive-models-of-development-teams-and-the-systems-they-build dev tenure half life 3.1 years code half-life 13 years
- 11. The documentation problem :( There are many different causes of docs (caused by different kinds of people) Some programmers don’t love writing docs* Programmers will leave your team Writing good documentation is hard** * but some do! ** but not as hard as programming, obviously 11@PeterHilton •
- 12. Tactics for avoiding the need to write the docs
- 13. How far will you go? You don’t have to write docs if you leave your mobile phone number in every source file. @PeterHilton • 13
- 14. @PeterHilton • 14 Constructive laziness is when you’re lazy about doing, but not lazy about thinking. @DenisHowlett
- 16. Documentation avoidance applies constructive laziness to software documentation @PeterHilton • 16
- 18. Just-In-Time Documentation 1. Don’t write the docs. 2. Bluff, ‘it’s on the wiki’. 3. Still don’t write the docs. 4. If they come back, feign ignorance. 5. Then write it. 6. Later, casually mention that you ‘found it’. 18@PeterHilton •
- 19. goelshivi / PD Alternatively, take time to patiently explain your code
- 20. Reverse just-in-time (JIT) documentation Instead of writing documentation in advance, you can trick other people into writing JIT documentation by asking questions in a chat room (and then pasting their answers into the docs) 20@PeterHilton •
- 21. The handover delusion A common management fallacy is to assume that a developer who never writes documentation can somehow ‘write everything down’ before leaving the team. 21@PeterHilton •
- 22. Pair programming Pair programming is far cheaper and more effective than documentation … but only if the other programmer is (still) available. 22@PeterHilton •
- 24. ‘A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments.’ @KevlinHenney 24@PeterHilton •
- 25. Acknowledge that writing docs is a specialist skill On a cross-functional development team, not everyone is good at visual design. The same goes for writing about code. Work out who is a better writer … then get him or her to write the docs. Maybe even hire a technical writer. 25@PeterHilton •
- 26. jameswragg / CC
- 27. // Calculates kitten cuteness. Integer getCuteness() // Returns a kitten ID. String findKitten(String name) // Check if kitten is alive. if (airway && breathing && circulation) /** * @author Peter Hilton */ public class Kittens Integer calculateCuteness() KittenId findKitten(String name) boolean alive = airway && breathing && circulation; if (alive) // Use version control!
- 28. /** * Calculates cuteness in the range 0-10. * * Idempotent; does not modify the kittens. * * Reference Kitten (previous slide) defines cuteness score 10. * * Returns 0 for dead kittens (not cute). * * Throws NullKittenException if list contains a null kitten. * * Throws IllegalKittenException if list contains a non-kitten. */ Integer calculateAverageCuteness(List<Kitten> kittens)
- 29. Documentation avoidance Constructive laziness Just-in-time documentation Pair programming Getting someone else to write the docs Code refactoring - especially better naming Type safe programming Unit tests - API usage example tests 29@PeterHilton •
- 30. Failing to get away with documentation-avoidance
- 31. 31@PeterHilton • smlp.co.uk / CC BY 2.0 ‘Just read the code’ ‘It’s self-documenting’
- 32. What we talk about when we talk about code Write the introduction: purpose, scope, summary Explain the design: constraints, limitations, alternatives Give examples Add explanations for new team members 32@PeterHilton •
- 33. @PeterHilton • Lesley Mair / CC BY 2.0 Why?
- 34. Even perfect code cannot explain why it exists Explain the why @PeterHilton • 34
- 36. Compromising on documentation-avoidance Part of documentation avoidance is knowing when you’re going to have to write docs anyway. Then it’s about writing as little as possible… 36@PeterHilton •
- 37. Writing docs that aren’t ‘documentation’
- 38. There’s more than one kind of documentation You can describe software in many ways: more code, diagrams, chat, commits, docs. Text isn’t necessary the hardest or most effort, but keep it close to the code, and don’t forget maintenance. 38@PeterHilton •
- 39. Code comments Programmers get weird about code comments… Comments are often a taboo subject … but a feature of every programming language Comments are just another documentation tool … and not the worst way to write documentation Comments are closer to the code than other docs. 39@PeterHilton •
- 40. Capitalized, short (50 chars or less) summary More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
- 41. Commit messages (instead of comments) Write a short subject line. Add additional paragraphs to explain: why a change was necessary, how the change addresses the issue, what changed, why you made the change the way you did, consequences of the change 41@PeterHilton •
- 42. README-Driven Development ‘… we have projects with short, badly written, or entirely missing documentation… There must be some middle ground between reams of technical specifications and no specifications at all. And in fact there is. That middle ground is the humble Readme.’ http://tom.preston-werner.com/2010/08/23/readme-driven-development.html 42@PeterHilton •
- 43. Today I Learned (TIL) Short independent articles that each document one thing. Markdown files in a GitHub repository.
- 45. Tutorials, instructions & other written forms 45@PeterHilton • Something you’re working on doesn’t have docs. A solution to a specific problem is useful for someone. The only tutorial on a topic can get a lot of page views. You might even get a little bit famous in a community. Publish on a blog, on Stack Overflow or in a TIL repository.
- 46. 46@PeterHilton •
- 48. Public API docs The best API docs are written by hand (tools are for layout). Structure and consistency are crucial. API docs generators solve structure and layout - a less interesting problem - and don’t write docs for you Java/Scaladoc, Swagger, Silk, Spring REST Docs 48@PeterHilton •
- 49. Chat rooms Team chat is essential for development teams … and we’ve come a long way since IRC Chat can replace some documentation if search is good (search is why it’s worth paying for Slack) Cheaper alternatives include: HipChat, Gitter Lack of search is why you don’t use Skype for group chat 49@PeterHilton •
- 50. Wikis & other tools for talking code Despite the alternatives, you usually still need a document- based system for internal software documentation. :) Wikis replaced Microsoft Word docs on shared drives. :( Wiki software has been stagnant for a decade. Confluence turned into something else. Modern alternatives are closed platforms. GitHub Wiki might be as good as it gets. 50@PeterHilton •
- 51. /** * Calculates cuteness in the range 0-10. * * Idempotent; does not modify the kittens. * * Reference Kitten (previous slide) defines cuteness score 10. * * Returns 0 for dead kittens (not cute). * * Throws NullKittenException if list contains a null kitten. * * Throws IllegalKittenException if list contains a non-kitten. */ Integer calculateAverageCuteness(List<Kitten> kitten)
- 52. Enrico / CC BY 2.0
- 53. 53@PeterHilton • Erich Ferdinand / CC BY 2.0
- 55. ?- How many Prolog programmers does it take to change a lightbulb? false
- 56. Take-aways: tools, tips & practical techniques
- 57. Write a project/project introduction Write an introduction (README) for your software: Explain the purpose and scope Summarise what it does. Write installation and development instructions. Publish tutorials online. Don’t forget to write (good) code comments. 57@PeterHilton •
- 58. Write good code comments Try to write good code first (and tests!). Try to write a one-sentence comment. Refactor the code (make it easier). Delete unnecessary comments (just like unused code). Rewrite bad comments (all good writing requires rewriting) Add detail where needed. 58@PeterHilton •
- 59. Comments are not the enemy. Meetings are the enemy! @PeterHilton • 59
- 60. Write detailed installation/test instructions Detailed instructions make every keystroke/click explicit. ‘On the process start form, in the Answer field, enter 42.’ Surprisingly easy to write. Surprisingly valuable (in time that readers save). Automate installation/testing where you can … and write procedures for what’s left. 60@PeterHilton •
- 61. Understand who and what the docs are for ‘There should be documentation’ isn’t enough. Work out who needs the docs: your future self, other developers, users, managers & other stakeholders. Use documentation to reduce costs, e.g. installation effort or team handover. 61@PeterHilton •
- 62. Aim to write the Minimum Viable Documentation. The rest is waste. @PeterHilton • 62
- 63. Specifications Some complex systems require documentation for a specific area that is hard to understand Architecture diagram UML diagram Data dictionary Process model Business rules 63@PeterHilton •
- 64. Choose the right kind of docs README Installation instructions (step-by-step) Code comments TIL (Today I Learned) Tutorials API documentation Specifications (rarely) Presentations :) 64@PeterHilton •
- 65. Use Markdown or similar Things that seemed like a good idea at the time: troff, SGML, RTF, DocBook, XHTML, XSL-FO Things that seem like a better idea now: Markdown, reStructuredText, AsciiDoc The ultimate text markup language is still: HTML 65@PeterHilton •
- 66. Use humour There’s no rule that says that jokes aren’t allowed. Insufficiently serious documentation is probably not your biggest problem. Staying awake might be. Humour isn’t magic. There are several practical theories of what’s funny. 66@PeterHilton •
- 67. Choose an appropriate tool that you like GitHub repo - plain Markdown files GitHub Pages - Jekyll site builder GitHub Wiki - Gollum wiki Read the Docs - Sphinx docs builder Asciidoctor - asciidoc to many formats Swagger - API docs structure and layout Silk - API docs 67@PeterHilton •
- 68. 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
- 69. Summary
- 70. Summary Writing documentation sucks; … but has value and isn’t going away You need documentation, … but not very much of it Many developers hate writing it, … but not all of them You hardly have to write any; … you might find someone else to write the rest 70@PeterHilton •