The document discusses the challenges of software documentation, highlighting various causes such as management demands and developer resistance. It suggests techniques to minimize documentation efforts, including just-in-time documentation, code comments, and leveraging team communication tools. Ultimately, it stresses the importance of creating adequate documentation while recognizing the value of concise and effective communication methods.

1. @PeterHilton
http://hilton.org.uk/
Documentation avoidance
for developers
How to get away with less documentation
and spend more time writing code
#WriteTheDocs

2. The documentation
problem

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

7. 7@PeterHilton •
James Whatley / CC BY 2.0
Shakespeare wrote
what is now
Legacy Poetry.
Even good code gets old.

8. Developers
look for
documentation
in legacy
system
Jean-François
Millet
1857
Oil on canvas
classicprogrammerpaintings.com

9. 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

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. Tactics for avoiding the
need to write the docs

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. @PeterHilton • 13
Constructive laziness
is when you’re lazy
about doing, but not
lazy about thinking.
@DenisHowlett

15. Documentation
avoidance applies
constructive laziness to
software documentation
@PeterHilton • 15

16. It’s on
the wiki!

17. 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 •

18. goelshivi / PD
Alternatively, take time to
patiently explain your code

19. 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 •

20. 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 •

21. Pair programming
Pair programming is far cheaper and
more effective than documentation
… but only if the other programmer is
(still) available.
21@PeterHilton •

23. ‘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 •

24. 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 •

25. jameswragg / CC

26. // 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!

27. /**
* 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)

28. 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 •

29. Failing to get away with
documentation-avoidance

30. 30@PeterHilton •
smlp.co.uk / CC BY 2.0
‘Just read the code’
‘It’s self-documenting’

31. 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 •

32. @PeterHilton •
Lesley Mair / CC BY 2.0
Why?

33. Even perfect code
cannot explain
why it exists
Explain the why
@PeterHilton • 33

35. 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 •

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.
37@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.
38@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
40@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 41@PeterHilton •

44. Today I Learned
(TIL)
Short independent
articles that each
document one thing.
Markdown files in a
GitHub repository.

46. 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.

47. 45@PeterHilton •

49. 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 •

50. 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 •

51. 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 •

52. /**
* 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)

53. Enrico / CC BY 2.0

54. 52@PeterHilton •
Erich Ferdinand / CC BY 2.0

55. http://www.j-paine.org/dobbs/prolog_lightbulb.html

56. ?- How many Prolog programmers does it take
to change a lightbulb?
false

57. Take-aways: tools, tips &
practical techniques

58. 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 •

59. 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 •

60. Comments
are not the enemy.
Meetings
are the enemy!
@PeterHilton • 58

61. 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 •

62. 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 •

63. Aim to write the
Minimum Viable
Documentation.
The rest is waste.
@PeterHilton • 61

64. 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 •

65. 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 •

66. 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 •

67. 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 •

68. 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 •

69. 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

70. Summary

71. 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 •

72. @PeterHilton
http://hilton.org.uk/ #WriteTheDocs