My takeaways from "Docs for Developers"
As I mentioned in Tools and techniques to overcome documentation writer’s block, I became fully aware of the nuance of good documentation only when I started writing it. That was a big "you learn how much you don't know" moment for me.
To catch up, I reached for "Docs for Developers: An Engineer’s Field Guide to Technical Writing" by Jared Bhatti, Sarah Corleissen, Jen Lambourne, David Nunez and Heidi Waterhouse. In this article, I will share my notes from reading it.
Learn your users
In the first chapter called "Understanding your audience", the authors suggest trying to describe the core characteristics of your user. They make a point to consider:
- Developer skill
- Programming languages
- Developer environment
- Operating system
- Team role
The argument is that a site reliability engineer may require a different perspective on a subject than a front-end developer, which should be reflected in the answers to the points above. Only when you know who your users are, you may start to wonder what are their needs and how can you meet them.
Be mindful about linking to other resources
The authors note that while linking to other resources is generally a good practice, it should be used with caution. To decide, consider what type of content you are creating.
For example, users visiting a "how-to guide" expect clear and complete instructions to solve their problem. Linking to outside resources or articles may be considered a distraction. However, when users enter the "core concepts" article, they are in an "exploration mode". They want to look at this particular part of the system from a bird's eye view, so pointing to other landmarks may be welcome.
Evaluate the users' journey
If you want to review the structure of your documentation, try looking at it as a traversal. You want your users to go through your documentation in a logical, perhaps "top-down", order.
Simulate (or better, organize usability testing and observe) the path your users may go down. The happy user journey starts in the "getting started" article and leads through discovering architectural objectives, to solving scoped problems. If what you witness looks more like going through a maze, your documentation should do a better job navigating the users.
Respect the users' attention
You hear clichés about how poor our attention is all the time, but putting it in the context of documentation was quite refreshing to me. The authors start one of the sections in chapter 3 "Drafting documentation" by stating two paradoxical truths about readers of documentation:
- Readers come to your documentation looking for information.
- Readers read very little of what you write.
To accommodate those two circumstances, you have to be mindful of users' attention. You can achieve it through:
- being deliberate about everything you write
- making your content skimmable (by using proper structure and text boldening)
- stating your critical information first
- breaking up large blocks of text
Examing your first draft
I put an emphasis on pushing your first draft outside the door early in the Tools and techniques to overcome documentation writer’s block article. The authors of "Docs for Developers" offer a set of questions to determine if that first draft achieved the expected result:
- Does the headline summarize the document's goal?
- Do headings adequately summarize the document?
- Does your draft address your reader's needs from start to finish?
- Does the flow of information make sense to your reader?
- Does your draft correctly follow any documentation patterns or a template?
- Have you tested and verified that any and all procedures work?
You can implement it as a personal checklist for all your documentation drafts.
After reading "Docs for Developers", my appetite has only increased. If you have any recommendations for documentation or development books, shoot them my way on Twitter!