I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Lauren is a tech writer at Puppet Labs. She focuses on the Forge, a repository of community modules for Puppet. At Puppet the docs team falls under engineering, and the writers are embedded within the various development teams.
The challenge they face is that users have different needs, environments, workflows, and most importantly, levels of experience. The experiment Puppet tried was the beginner’s guide to modules. They’re in the process of writing an advanced guide, which would incorporate what they learned from the beginner’s guide.
In the first draft they took inspiration from textbooks. They brain-dumped everything in to a Google Doc which they then sorted in to 4 sections. They wanted to present heaps of information so that everyone who needs a foundational knowledge of modules would be satisfied. It was immediately apparent that the document was overwhelming. It was hard to approach and the first section in the document was disproportionately huge.
What they realized was that the first thing they needed to do was create sign posts within each section along with sub-sections. The took a more orientation-based approach to writing the document. This second take at the document produced something much more readable and comprehensible. Large paragraphs were broken up and edits were geared toward orienting the user. It was still really difficult to navigate and locate distinct items, though. You constantly were going back and searching for where you left off; it wasn’t easy. In short, the doc at this point was really readable but not usable.
They realized they’d been working on a treatise, not a guidebook. They dropped the academic standpoint and textbook approach. What they really wanted was a doc that people would want to look at more than once, not something they’d only read because of its challenging nature.
“The doc was really readable, but not usable.” #writethedocs Put that on my cube wall.
— Austin Schaefer (@AncientToaster) May 6, 2014
In hindsight it seems really obvious that a step-by-step approach was necessary. It didn’t occur to them to take this approach, though, until they were 2 drafts in. The final version has a table of contents, headings, steps, introductory sentences and examples. All around it was a huge improvement.
Lauren couldn’t help from thinking about future improvements, though. There wasn’t enough get-your-hands-dirty details in the beginner’s guide. It was too high-level at times. She’s taking some of these lessons and applying them to the advanced guide to modules.