Documentation avoidance for developers


Published on

However good your code, other people never seem to get it. Instead they ruin your day (and your productivity) by asking questions and expecting documentation. You need to know how to explain code without getting stuck in meetings or spending half your time on the only thing you hate more than meetings: writing documentation. Instead, you aim for constructive laziness: tactics that give you more time to write code.

This talk teaches you how to avoid writing documentation, by making it unnecessary or delegating the work to someone else. You will also learn how to deal with the awkward situation when you can’t get away with avoidance or delegation, and have to write the documentation yourself.

This talk explores what we talk about when we talk about code, how we do it, and the tools we use. You can often find a better tool than documentation, but not always. Not everyone writes detailed specifications these days, but remote working and distributed teams make written explanations more valuable than ever. Talking face to face requires less effort, but you rarely or never meet the authors of most of the code you see. Software craftsmanship has failed to make written documentation unnecessary. Instead we shall turn to README-Driven Development, comments evasion, documentation-avoidance, just-in-time documentation and the art of not writing it in the first place.

Published in: Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Documentation avoidance for developers

  1. 1. @PeterHilton Documentation avoidance for developers How to get away with less documentation 
 and spend more time writing code #WriteTheDocs
  2. 2. The documentation problem
  3. 3. What are the causes of software documentation? @PeterHilton • 3
  4. 4. Justin Ennis / CC BY 2.0
  5. 5. ‘M&Ms, 
 managers and meetings’ M&Ms generate demand for software documentation. Meetings are failure demand. @PeterHilton • 5
  6. 6. 6@PeterHilton • Michael Coghlan / CC BY-SA 2.0 Unfamiliar domains
  7. 7. 7@PeterHilton • James Whatley / CC BY 2.0 Shakespeare wrote 
 what is now Legacy Poetry. Even good code gets old.
  8. 8. Developers 
 look for documentation in legacy system Jean-François Millet 1857 Oil on canvas
  9. 9. Rob Smallshire - dev tenure half life 3.1 years code half-life 13 years
  10. 10. 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 10@PeterHilton •
  11. 11. Tactics for avoiding the need to write the docs
  12. 12. How far will you go? You don’t have to write docs if you leave your
 mobile phone number 
 in every source file. @PeterHilton • 12
  13. 13. @PeterHilton • 13 Constructive laziness is when you’re lazy about doing, but not lazy about thinking. @DenisHowlett
  14. 14. Documentation avoidance applies constructive laziness to software documentation @PeterHilton • 15
  15. 15. It’s on the wiki!
  16. 16. 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’. 17@PeterHilton •
  17. 17. goelshivi / PD Alternatively, take time to patiently explain your code
  18. 18. 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) 19@PeterHilton •
  19. 19. 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. 20@PeterHilton •
  20. 20. Pair programming Pair programming is far cheaper and more effective than documentation … but only if the other programmer is (still) available. 21@PeterHilton •
  21. 21. ‘A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments.’ @KevlinHenney 23@PeterHilton •
  22. 22. 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. 24@PeterHilton •
  23. 23. jameswragg / CC
  24. 24. // 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!
  25. 25. /** * 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)
  26. 26. 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 28@PeterHilton •
  27. 27. Failing to get away with documentation-avoidance
  28. 28. 30@PeterHilton • / CC BY 2.0 ‘Just read the code’ ‘It’s self-documenting’
  29. 29. 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 31@PeterHilton •
  30. 30. @PeterHilton • Lesley Mair / CC BY 2.0 Why?
  31. 31. Even perfect code cannot explain why it exists Explain the why @PeterHilton • 33
  32. 32. 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… 35@PeterHilton •
  33. 33. Writing docs that aren’t ‘documentation’
  34. 34. 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. 37@PeterHilton •
  35. 35. 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. 38@PeterHilton •
  36. 36. 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
  37. 37. 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 40@PeterHilton •
  38. 38. 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.’ 41@PeterHilton •
  39. 39. Today I Learned (TIL) Short independent articles that each document one thing. Markdown files in a GitHub repository.
  40. 40. Tutorials, instructions & other written forms 44@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.
  41. 41. 45@PeterHilton •
  42. 42. 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 47@PeterHilton •
  43. 43. 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 48@PeterHilton •
  44. 44. 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. 49@PeterHilton •
  45. 45. /** * 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)
  46. 46. Enrico / CC BY 2.0
  47. 47. 52@PeterHilton • Erich Ferdinand / CC BY 2.0
  48. 48.
  49. 49. ?- How many Prolog programmers does it take 
 to change a lightbulb?
  50. 50. Take-aways: tools, tips & practical techniques
  51. 51. 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. 56@PeterHilton •
  52. 52. 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. 57@PeterHilton •
  53. 53. Comments are not the enemy. Meetings are the enemy! @PeterHilton • 58
  54. 54. 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. 59@PeterHilton •
  55. 55. 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. 60@PeterHilton •
  56. 56. Aim to write the Minimum Viable Documentation. The rest is waste. @PeterHilton • 61
  57. 57. 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 62@PeterHilton •
  58. 58. Choose the right kind of docs README Installation instructions (step-by-step) Code comments TIL (Today I Learned) Tutorials API documentation Specifications (rarely) Presentations :) 63@PeterHilton •
  59. 59. 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 64@PeterHilton •
  60. 60. 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. 65@PeterHilton •
  61. 61. 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 66@PeterHilton •
  62. 62. 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
  63. 63. Summary
  64. 64. 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 69@PeterHilton •
  65. 65. @PeterHilton #WriteTheDocs