Your life can be so much easier once you know how to write documentation — good, helpful documentation that actually gives its users what they need from it.
After all, everyone reads documentation:
- Marketing teams work with playbooks — a sort of marketing documentation.
- Support and technical teams use user guides, installation manuals, code notes — “core” technical documentation.
- Others rely on standard operating procedures, reference material, process documents, checklists — typical company knowledge documentation.
Customers, too, use customer-facing documentation to learn their way around a solution or debug their issues on their own (tier 0 support).
While there’s no one standard way to create all this documentation, the fundamental steps remain the same. But before we see those, let’s take a quick look at the different documentation types. Based on its purpose, a documentation piece can be one of four types.
Types of documentation
In his talk on the types of documentation, Daniele Procida or Divio AG categorizes documentation into four types:
- learning-oriented tutorials
- goal-oriented how-to guides
- understanding-oriented discussions
- information-oriented reference material
As you can understand from how he puts it, every piece of documentation has a different objective, and those responsible for the documentation must establish it each time they set out to create one.
With that in mind, let’s start with our guide on how to write documentation.
Determine if you truly need to document it
Your product might do a hundred things. There may be even more ways to customize it. You could have a codebase of thousands of lines. And you might also be generating a LOT of knowledge in your daily work.
But it’s not possible to document everything… and not everything needs to be documented.
So before answering the “how to write documentation” question, know if you must document it at all.
Before you document, think about your target readers. The target readers for your documentation could be anyone from an end-user to your software developer(s) or HR person. Are they knowledge workers? Think about what these target audiences struggle with… and if you can genuinely empower them to do better by documenting.
Also, think about how they will use it. Think in terms of how the intended users will interact with your documentation.
Will your customers follow your documentation step-by-step to get started with your solution? Which makes your documentation “goal-oriented.”
Or will your developers use it as they work and collaborate on your next release cycle? In which case, you’re looking at “understanding-oriented” documentation.
Or will your HR resource refer to it when processing applications? You have “information-oriented” documentation here.
And will your documentation really help them?
Other than these, you might also want to think about how your documentation efforts will help you at a higher level:
- Will your documentation improve your tier zero support and enable your end-users to resolve their issues on their own (deflection)?
- Would it make your teams get better at what they do?
- Will your team get more productive?
Find out when to document it
The general idea is to not start too early (or late).
Unless you aren’t sure about how a process is actually going to play out or how you’re going to execute your “vision,” it’s best not to document it and wait until things materialize a bit.
For example, if you’re planning a significant update in the next quarter and the work is only in the high-level conceptual stage, don’t engage documentation resources just yet.
This is the “Agile” approach to documentation.
Often, the best time to do certain documentation types (like procedures and processes) is when you’re actually executing them.
Zero in on the best way to document it
Depending on the types of documentation you need, you need one or multiple places to hold it all. These work as your single source of truth.
Yelp’s Chastity Blackwell shares some of the frustrations when all your documentation isn’t stored nicely in one place:
You’ve got a doc that explains everything about that service and you’re sure the info you need to solve this incident is in there — somewhere. “You can try looking for that in the wiki, or maybe it’s in the Google Docs repo. Oh, and I’ve got some notes in my home directory, and I think I saw some email about that a while ago.”
Naturally, you don’t want this to happen to you. That’s why you must choose your documentation tool(s) thoughtfully. If you’re documenting for end-users, it’s best to use an easy-to-populate knowledge base solution like Heroic Knowledge Base. You can find some alternatives here.
If you’re documenting for your teams, go with a wiki solution like WikiPress or an internal knowledge management solution Heroic Knowledge Base (yeah, it doubles up as one!). Or, check out some of these options for knowledge management solutions.
Finally, if you’re documenting code, you might want to consider some of the more specialized technical documentation solutions. Some general-purpose knowledge base solutions like Heroic Knowledge Base work just as well as technical documentation solutions too.
When you choose your documentation system, make sure to pick one that’s easy to update because you might find yourself updating your documentation often! Your documentation tool should also offer some excellent searching functionality.
Decide what to write
Because documentation can take so many forms, it’s essential to finalize a format before writing it.
For example, at HeroThemes, we use a mix of FAQs, installation tutorials, troubleshooting guides, lists of tips and tricks, and others for our customer-facing documentation. Most of our customers also use a similar composition.
Depending on the documentation you’re producing and for whom, you’ll need to know what all forms your documentation can take. Jacob Kaplan-Moss talks in detail about these in What to write. He explains how tutorials, topical guides, and reference material make up the bulk of documentation in most cases:
- Tutorials: Tutorials or how-tos are the most basic form of documentation. For our customer-facing documentation, tutorials are our how-to resources that our users use to add a knowledge base to their webs
ite with our plugin or populate it with articles. - Topical guides: Topical guides tend to go a lot deeper than tutorials and cater to more specialized topics. For us, these are our guides on topics like translation and integrations. We loosely categorize these as advanced topics.
- Reference: In our customer-facing documentation context, this type has information on our integrations with our partners that our users might find helpful when setting up their integrations. Or links to any stuff they might find useful when implementing any of our HeroThemes solutions.
Start with a README file (and build upon it)
With all that clear, now you’re ready for the writing part. The actual writing part of documentation starts with a README file. Think of it as the cover page or outline for your documentation.
If you’re working on your code’s documentation that your (developer/tester/optimizer) colleagues will use, your README file will look a certain way.
And if you’re writing customer-facing documentation, you might want to adapt it to make sense for the intended audience and the work it needs to get done. The content, though, remains the same more or less. Below, you can see how a support article explaining how an integration works start with a cover page thing of its own.
Now, just take your READMe file or your documentation’s outline and fill it out one section at a time. Here are a few resources from our blog to help you fill out your documentation:
- The Ultimate Knowledge Base Article Template (Infographic): We dug into our customers’ most successful knowledge base articles and decoded how a good knowledge base article looks like. Such articles make up a significant part of your user-facing documentation, so use this infographic to create them at record speed.
- How to Write Thorough Step-By-Step Standard Operating Procedures (SOPs): This is a quick how-to on writing how-tos or standard operating procedures that offer step-by-step instructions on how to complete the intended work — very useful when creating an internal company wiki or knowledge base.
- What Is Process Documentation? And How to Document Your Processes the Right Way: Another quick how-to on writing process documentation, an essential part of your internal company knowledge documentation mix.
- How to Write Frequently Asked Questions & 5 Simple Ways to Write the Perfect Answers to Your FAQs: These two posts will help you whip up your FAQs within an hour and deflect a lot of pre-sales queries like a boss.
Once done, don’t forget to add a reviewing and testing part.
Reviewing is an essential part of the documentation process. It helps you ensure that your documentation actually works. In his five-step documentation reviewing process, technical writer Tom Johnson says that the first stage is unmissable where you — the documentation writer — make “the product work” for yourself following the steps you’ve written.
Set an update schedule
Documentation starts staling as soon as it’s published. So you need an update schedule.
Your update frequency will depend on the documentation you’re looking at. For instance, your user-facing documentation will need updates only when you update your product.
Developer-facing documentation — technical code documentation — is forever ongoing ( inline documentation).
Your internal knowledge/work documentation, on the other hand, could use updating each time something changes — for example, when you replace your current project management tool or even when you simply discover a more optimized way of doing some work. Tribal knowledge capturing and general knowledge capturing are some of the ongoing exercises in such documentation.
When it makes sense, maintain a change log in your documentation so that users don’t feel lost when they see an updated version.
Also, as part of updating your documentation, get rid of the obsolete and duplicate files. A search in your documentation should never return multiple versions of the same support content. Each topic should only take one resource.
Wrapping it up…
Once you’ve finetuned this general guide on how to write documentation to suit your documentation workflow, document your documentation writing process
Doing so will help you not just standardize your documentation writing but also enable others to build upon it because documentation is always ongoing.
Over to you… How do you currently approach writing documentation?
The post How to Write Good Documentation (A Step-by-Step Guide) appeared first on HeroThemes.