Documentation avoidance for developers
How to get away with less documentation and spend more time writing code
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.
Video
Documentation avoidance for developers at ProgSCon London 2016
Slides
Reviews
Thoughts on ‘Documentation Avoidance for Programmers’, by Tom Johnson
Outline
- Constructive laziness, or the art of having more time to write code
- Meetings: the ultimate failure demand
- Legacy code, developer half-life & other industrial irritations
- What I talk about when I talk about code
- Ubiquitous languages, long words & other jargon
- Different kinds of automated tests
- There’s more than one way to talk about code
- Code comments: the ultimate taboo
- Just-in-time documentation & the art of not writing it
- README-Driven Development
- Commit messages
- Tutorials, instructions & other written forms
- Chat rooms, wikis & other tools for talking code
Conference presentations
- ProgSCon London - 22 April 2016
- Joy of Coding - 17 June 2016 (rated 8.1/10, 47 votes - third highest score of 12 talks)
- Voxxed Days Thessaloniki - 21 October 2016
- J-Fall - 3 November 2016 (rated 4.2/5, 64 votes)
- Topconf Tallinn - 16/17 November 2016
