Exert less mental energy
Get work done without thinking too hard and exerting the least amount of effort possible.
Create consistency
Ensure that the same information, processes, and plans are being consumed by your readers in a consistent way.
Minimize workload
Onboard teammates quickly and efficiently so they can start getting work done right away.
Improve company branding
Make a statement about how you treat your external customers and internal employees by being supportive and helpful.
All documentation should aim to accomplish 2 main things:
Inform users
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.
Internal documentation
Team documentation
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.
Reference 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.
Project documentation
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.
EXTERNAL DOCUMENTATION
System documentation
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.
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.
Including examples in your documentation offers a huge 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.
Creating documentation
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.
Research
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.
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.
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.
Format
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.
Review
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.
Publish
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!
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.
Hit the ground running
The best documentation is clear, concise, informative, and most importantly, adds value for its audience. Explore team collaboration software like Confluence for your documentation, and spend less time hunting things down, and more time making things happen