Beginner's Guide to Documentation: What to Know
Michael Nicholson
Cloud Solution Engineer
We all use software. And we all learn - to some degree - how to use it. That includes us here at Divio. Approaches to learning how to use software vary. We may learn as we go, read up guides beforehand or jump in at the deep end. Inevitably, how successful we are using software depends on how we learn how to use it.
This is why having clear software guides is crucial. Guides allow users to learn how to effectively use products, along with understanding how it works. Without them, the potential of what software can achieve may not be reached. You might also have some grumpy users along the way. As long as there's software, we need these types of guides.
Definition of documentation
Documentation is a term given to a group of support guides for a software product or service. These guides cover what users need to know about this product. This can include how to use it, how it works and how to achieve a particular outcome. In its simplest form, documentation covers: what it is, how it works and what to do if something goes wrong.
Taking on a documentation project can be a big task, especially if you're new to it. Software is complex and multifaceted. It's important to take a systemised approach to a documentation project, no matter what level you're starting from. To make this a little easier, we'll share what you need to know as a documentation beginner. We'll be going through:
Why have documentation?
The importance of good documentation practices
Common problems to be aware of
Takeaways
Why have documentation?
An effective documentation system could be one of your most valuable resources. This is true whether you're creating public-facing or internal documentation. It should be approached as a necessary part of your product offering.
External users, especially customers, need to know how to use your product effectively. If this isn't easy to learn, they'll go elsewhere to find an alternative. Documentation is critical for customer retention. It also impacts conversion rates. If potential users can't easily understand how to use your software, you'll lose potential leads. This might end up impacting your reputation too. Your product may be considered too complicated or not user friendly.
Regarding internal documentation, having a robust system should result in reduced downtime. User intuition is just not reliable enough when it comes to learning software. Complex systems have a wide range of applications. This leaves considerable room for human error. Having clear, easy-to-understand documentation will mean fewer problems to solve and less firefighting.
Ultimately, users won't be able to use your product effectively without documentation.
Let's sum up the benefits of documentation:
Documentation makes software products easier to use
It results in less downtime
It promotes user retention and brand reputation
The importance of good documentation practices
We've established the importance of documentation systems. Now, let's look at what good documentation looks like. We'll also cover why it is important to implement specific practices and how they will benefit your users.
Before you start
You need to have a clear understanding of what you're trying to achieve with your documentation. It's useful to think of documentation as 'documentations' plural. Approaching documentation as isolated guides all in the same format doesn't take in the scope of user needs and their objectives. To make things easier, there are different types of documentation formats that suit different user requirements. We'll discuss what these are further on.
Understanding different users is key. Consider who they are - are they internal (developers, marketing team, sales team, new employees) or external (customers, contractors)? Remember, any prior knowledge they have on your product or technology will vary depending on the type of user. It's important to keep this in mind when writing for them.
The success of these resources is dependent on clarity. Everything needs to be written so it's easily understood. Think 'accessible and comprehensive'. This is why prior research is so valuable. You may want to look at use cases, conduct user interviews and analyse user journeys. Understanding the type of user and the questions they are likely to ask will make the writing process smoother. Documentation projects like this can be very big, especially after doing extensive research. Consider creating a priority list of what needs writing first. Is there anything that could be streamlined or condensed?
Identifying documentation types and their functions
There are four types of documentation, each with a unique function and purpose. All four are necessary but very different from each other. They apply to both internal and external users, but follow distinct user journeys. Approaching documentation creation from this perspective will result in a more manageable process. The writer knows who they're writing for, and the user will easily understand the documentation. You can use your user research to inform the documentation type you choose.
TUTORIALS
These focus on learning about the product. Tutorials take users step-by-step through how to use different parts of a product. There is an end goal to reach: to complete the exercise. To help users achieve this, tutorials should be clear, accessible and with a single focus. All relevant information should be included.
Tutorials should be the starting point for new users because they act as an introduction to your product. Learning how to do something before learning how it works is easier to understand. The effectiveness of tutorials can have a significant impact on user retention. Ultimately, you want your user to feel confident using your product, and to want to repeat what they have learned.
HOW-TO
These focus on achieving a specific outcome. Similar to tutorials, they take a step-by-step approach. The difference is that users want to solve a particular problem. Think of these as the next logical step up from tutorials. Users need to learn how to use a product first before they ask for specific technical questions. The detail in a how-to guide doesn't need to be at the same level as a tutorial. Remember, users will be coming into them with some existing knowledge.
TECHNICAL REFERENCE
These detail how the product works in clear, technical descriptions. In software documentation, these will be led by how the code works. The focus here is on advanced information and facts. This type of documentation is for users already familiar with the product. At this stage, they'll want to understand how the whole system works. You can avoid basic concepts and how to perform common tasks.
EXPLANATION
These explain how the product works, give background and provide context. This type of documentation is for those who want to take a closer peek under the hood. They want to make connections across the software and understand the nuts and bolts. Information here is theoretical, rather than practical or descriptive.
Some of these may at first glance look like they overlap, but it is important to keep them separate within the documentation structure. This helps users find what they're looking for, as well as provide clear information.
Guiding principles
Once you've established what your documentation is going to address and what format you want to use, here are some best practices to keep in mind:
The writer should be someone who 1) understands this aspect of the product and 2) knows how to write for specific audiences.
Use a clear structure with an outline.
Use diagrams and illustrations to support your points. And don't forget to caption these.
Ensure the information is up-to-date, complete and correct. Remember, accuracy is critical.
Have someone read and sense check the documentation before it is published.
Save the documentation somewhere easy to find.
Common problems
It can be very tempting to go full-steam into a documentation project, especially with a large software product. However, it's useful to consider common challenges these projects face. This can help you mitigate, prevent or just be mindful of what to expect.
It can be difficult to keep documentation up-to-date. Consider regular reviews of documentation, as well as establishing a priority list.
You may have limited access to technical writers. Remember, developers and engineers aren't technical writers. In this case, consider how to implement updates to documentation into existing workflows.
Findability. This is largely an internal problem. External users can use Google to help them locate specific documentation. It's likely that workforce documentation will be saved in a wide range of locations. Centralisation may not be possible, so consider creating hubs that link out to these different systems.
Takeaways
Prioritising documentation not only benefits your users, but will also benefit your organisation. It may be a little daunting as a documentation beginner, but is absolutely worth the investment and time. The best approach when starting a new documentation project is to prioritise and understand different user needs. There are a wide range of tools, structures and practices you can use in your project. These can help establish a clear, accessible and useful documentation system that has a solid foundation and longevity.