Embed Size (px)
Citation preview
@PeterHilton
http://hilton.org.uk/
Documentation avoidance for developersHow to get away with less documentation and spend more time writing code
#WriteTheDocs
The documentation problem
What are the causes of software documentation?
@PeterHilton • 3
Justin Ennis / CC BY 2.0
‘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@PeterHilton •Michael Coghlan / CC BY-SA 2.0
Unfamiliar domains
Jam
es B
yrum
/ CC
BY-
ND
2.0
Homer’s Iliad is now
legacy poetry
Developers look for documentation in legacy system
Jean-François Millet
1857
Oil on canvasclassicprogrammerpaintings.com
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
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 •
Tactics for avoiding the need to write the docs
How far will you go? You don’t have to write docs if you leave yourmobile phone number in every source file. @PeterHilton • 13
@PeterHilton • 14
Constructive laziness is when you’re lazy about doing, but not lazy about thinking. @DenisHowlett
Documentation avoidance applies constructive laziness to software documentation
@PeterHilton • 16
It’s on the wiki!
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 •
goelshivi / PD
Alternatively, take time to patiently explain your code
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 •
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 •
Pair programming
Pair programming is far cheaper and more effective than documentation … but only if the other programmer is (still) available.
22@PeterHilton •
‘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 •
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 •
// 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!
/** * 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)
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 •
Failing to get away with documentation-avoidance
31@PeterHilton •smlp.co.uk / CC BY 2.0
‘Just read the code’ ‘It’s self-documenting’
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 •
@PeterHilton •Lesley Mair / CC BY 2.0
Why?
Even perfect code cannot explain why it exists Explain the why
@PeterHilton • 34
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 •
Writing docs that aren’t ‘documentation’
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 •
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 •
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
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 •
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 •
Today I Learned (TIL)
Short independent articles that each document one thing. Markdown files in a GitHub repository.
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@PeterHilton •
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 •
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 •
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 •
/** * 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)
Enrico / CC BY 2.0
53@PeterHilton •
Erich Ferdinand / CC BY 2.0
http://www.j-paine.org/dobbs/prolog_lightbulb.html
?- How many Prolog programmers does it take to change a lightbulb?
false
Take-aways: tools, tips & practical techniques
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 •
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 •
Comments are not the enemy. Meetings are the enemy!
@PeterHilton • 59
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 •
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 •
Aim to write the Minimum Viable Documentation. The rest is waste.
@PeterHilton • 62
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 •
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 •
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 •
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 •
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 •
M A N N I N G
Peter HiltonErik BakkerFrancisco CanedoFOREWORD BY James Ward
Covers Play 2
Play for Scala(Manning, 2014)
Peter HiltonErik BakkerFrancisco Canedo
http://bit.ly/playscala2p
Summary
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 •
