Elements of Successful Software Documentation
What does no one tell you about your documentation? Basically, it sucks. At least that’s what Community and Documentation Manager at Divio AG and Django Board Member Daniele Procida says. He brought to API the Docs London a number of reasons why you’re certainly doing your documentation wrong, and, more importantly, the way you could do it right.
Even better, he said, “The easier way is the right way.”
Procida believes that proper API documentation — and by extension probably all technical documentation — follows a strict four-part pattern: tutorials, how-to guides, reference guides, and discussions and explanations.
He said that, while you can and should link among the four parts, “Each of these four functions — each has a clear job” and shouldn’t reiterate on what the other has done.
Learning-Oriented Tutorials
Procida claims tutorials are the hardest of the four required documentation parts, but that doesn’t mean years of experience will help make you better at them. To the contrary, he says this piece is better for those that are less experienced, better at understanding from a beginner’s perspective.
He describes this piece as the “lessons that take the reader by the hand through a series of steps to complete the project.”
It also gives the reader a sense of accomplishment.
“Show the beginner that you can do something useful with the product.”
Procida, a foodie, used the extended metaphor of cooking throughout. This documentation piece he compared with teaching a child to cook.
“What you teach a child is pretty much irrelevant — the important thing a child learns is that the kitchen is an enjoyable place to do things,” he said, “and given them the tools to do it.”
So what goes into a great documentation tutorial? Like a good first chef’s lesson:
- It’s hands-on, you learn by doing.
- It starts at the “getting started” level.
- It inspires confidence so they trust both you and the software you’re giving them.
- The tutorial must work at any skill level or on any platform.
- It’s repeatable.
- It offers an immediate sense of achievement.
- It’s concrete, not abstract.
- It’s no place for an explanation beyond what they need in order to get from A to B.
- It contains no other distractions.
- It’s not a how-to guide, nor reference guide, nor discussion.
So based on these tips, the best person to write the documentation is often the newest member of your team — also what a great way to learn about the software from a user’s perspective! Also, don’t forget to pass your tutorials onto your QA testing team. Tests should constantly be performed to make sure that these guides not only are up-to-date but are constantly working alongside the code. Of course, automating these tests are even better.
Problem-Oriented How-to Guides
What’s good for the reader also usually is good for search engine optimization; Google likes information best when it is presented in this reader-friendly format. And then, of course, when folks Google something, it’s easier for them to stumble upon your documentation.
Procida describes these how-to guides as steps to overcome a specific problem, anticipating what’s needed, formatted in a way that makes it easily located by a search engine.
“A how-to guide is the answer to a question that a beginner may not be able to formulate,” he continued.
Procida contends that each how-to guide should:
- Include a series of steps.
- Focus on a goal.
- Address a specific question.
- Don’t explain anything unnecessary.
- Have a little flexibility — different ways of doing it.
- Concentrate on practical usability matters rather than theoretical completeness.
- Have good naming, like “How to Create a Class-based View.”
While this was a conference of technical documentation writers, there’s no doubt successful documentation is a collaborative experience. In this case, involving technical support and customer success teams in the creation process is key.
After all, they are the ones onboarding beginners and answering what can become your frequently asked questions. And of course, this saves your support team time and money in the long run.
Information-Oriented Reference Guides
Procida describes reference guides as the “technical descriptions of the machinery and how to operate it.”
This very information-oriented documentation piece typically involves some examples — best given in a different color text so they stand out to the user — but he argues that this portion isn’t about examples or concepts. Rather, he says it’s something austere and to the point, just the facts about the machinery.
Wikipedia entries are typically great examples of reference guides. Continuing his chef’s metaphor, he offered the simple Wiki for ginger, which has a good description and just the facts.
Procida went on to say that your documentation’s reference guides should contain the following, but nothing more:
- the same structure as your code base or software or whatever it is you’re describing,
- consistency like that of an encyclopedia, consistent in its form, tone and structure,
- only description matters,
- kept accurate and up to date.
He commented that this is the part developers tend to do best, but then they go ahead and spoil the reference material by adding other stuff from any of the three other parts or even pieces that shouldn’t be included in the documentation at all.
Understanding-Oriented Discussions and Explanations
While the first three documentation pieces clarify the What and the How, this piece works on the Why. Procida says it offers a wider view to help clarify some particular topic and to offer a greater understanding.
Explanations offer the following benefits to your users:
- They give context.
- They explain why things are the way they are, whether it is design decisions or there are historical reasons.
- They offer some alternatives and multiple approaches to the same question.
- They make connections so you can see how things can join up from a distance.
This section includes no instruction nor technical descriptions. It’s about offering the story that brings it all together. This section allows for a greater understanding of the code and offers the big picture, plus clarifies things. But don’t think this part lives in isolation as it still links to other aspects of the documentation.
But what does this perfect documentation look like? Unsurprisingly, Procida touts Django’s documentation as an example following this strict documentation quadrant properly. And he offered the tool Sphinx Python document generator as a way to help you organize and present it all.
In the end, he says that, if done correctly, your documentation “will be easier to write and to read.”
Finally, he reminded us to “be explicit in explaining how it’s organized up front” and to link between documentation.
And, of course, all good software documentation is written with the user in mind.
Feature image via Pixabay.
