Building better documentation
On this page:
You've just kicked off a project and now you’re on the hook to deliver documentation (cue: $#*&^!%).
Seem daunting at first? Sure - but we’re here to help! Below you’ll find documentation on documentation [(wink)] — a step by step guide with pro tips along the way—to lead you through the process. Let’s do this thing!
So why should I care?
In the simplest terms, documentation helps people do what they need to do. But, as with most inexplicably extraordinary things, it does much more than just help people get $#!t done. Documentation helps users and teams:
If you don't offer value, no one bats an eye in your direction. It's your job to shape the way your readers are thinking about the information you are offering and educate them on why they should care at all.
What is documentation?
Documentation is everything you think it is: a set of documents. A compass for your average end user. A playbook for the software engineer in you. In a more technical space, documentation is usually text or illustrations that accompany a piece of software. These docs act as a reference guide explaining how it works, how it operates, and how to use it. Software teams may refer to documentation when talking about product requirements, release notes, or design specs. Technical teams may use docs to detail code, APIs, and record their software development processes. Externally, documentation often takes the form of manuals and user guides for sys-admins, support teams, and other end users.
All documentation should aim to accomplish 2 main things:
1. Inform users
2. Enable users to successfully accomplish something
When starting any documentation, begin by defining the topic of interest, objective, or goal to help your audience understand what they are reading about right off the bat.
Types of documentation
As we've previously mentioned, documentation comes in all shapes and sizes, internal and external. Different types of docs require different voice, tone, formatting, contributors, audience, and content. The most common types are:
Team documentation helps illuminate the work that's being done so teams can, well, work as a team. These docs come in the form of project plans, team schedules, status reports, meeting notes, and anything else a team may need to work functionally and efficiently. This type of documentation is detailed, ensuring everyone stays on the same page.
System documentation details code, APIs, and other processes that tell developers and programmers what kinds of methods and functions can be used in developing specific software, as well as limitations and requirements. Code snippets, like example API calls and responses, are central to this type of documentation.
Reference documentation educates the company on important topics, processes, and policies. These may be policies created by the HR department, legal processes for hiring external vendors, or how-to articles on setting up your company benefits. Remember that reference documentation is written by a small pool of people for a large and varied audience, so digestible content is important.
End user documentation
User documentation is often the most visible type of documentation. It should be easy to read and understand, and updated with each new version of the software. It takes form in "Read Me" docs, installation guides, admin guides, product knowledge bases, and tutorials (the most helpful of the lot). And, like reference documentation, it's produced by a small pool of creators, for a large pool of consumers, so digestible content is important.
Project documentation is, naturally, project specific, and gives much-needed structure to product development. It includes proposals, product requirements documents, design guidelines or sketches, roadmaps, and other relevant information needed for development, with contributions coming from project managers, engineers, designers and more.
Including examples in your documentation offers a huge a value to your audience. They serve as a bridge to help understand concepts and ideas, and ensure the reader that you do in fact know what you are talking about.
The ultimate goal is to ensure your documentation is useful for the reader. We've provided you with tutorial-formatted documentation for your documentation (how meta) below to help make that task just a bit easier.
What do users need to know about your product, project, or API? Use your analytics tool to see what's being searched, browse online community forums and discussion groups, and conduct user research and usability testing. Make sure you also know your product and how to easily explain user questions, new features, and workflows.
2. Just start
Clearly state what's going to be covered in your documentation and why it should be valuable to the reader to kick it off.
3. Capture the deets
Create an outline and draft up your content. Write with an appropriate voice and tone (be human!) for your audience and be consistent and concise with your language. Communicate important details clearly.
Organize your page so it's easy to follow from beginning to end. Cut out fluff and break up long content with visuals like diagrams, screenshots, and images.
Get feedback on your their vs. there and to vs. too's. Ensure reviewers understand the goal of your documentation. This will help uncover confusing language or point out missing steps.
After revisions and edits, you're ready to go live! Publish your work and keep your ear to the ground for any feedback and comments. Documentation isn't something to set and forget!
As you can see, documentation isn't just putting a bunch of instructions and words together. There's a method to the madness, friends. Remember these guiding principles before, during, while you sleep, and after creating your documentation:
Keep it brief
Your documentation should have just the right amount of information to get the job done without raising a help ticket. Provide key points and the option for readers to go into further detail.
Visuals are key
Visuals are key to comprehension. Product design, code samples, in-product demos, screenshots, and video tutorials play a large role in helping a reader to fully understand the concept, the how-to, or the to-do. Also keep in mind the layout, legibility, and easily digestible chunks.
Know your audience
Take a walk in the user's shoes. Know your reader, take a stroll through their user journey of your product and your documentation. This should always guide how and what you write.