Let's say you just bought a new car and you're excited to drive it.
You don't need the salesperson in the passenger seat reminding you that it can go fast; you only need to know what speed you're going at right now. You also don't need to know how the engine is put together; you just need to know when to fill it up.
With new software, as with a new car, you don't need anyone to sell you what you already have and you don't need to know about every nut and bolt. You need to know how to operate it, and that's what product documentation is for.
What product documentation is
Product documentation is a type of technical documentation that helps the reader get set up with new software as smoothly as possible. The focus is on the user needs, use cases, and the product's capabilities. It's user-centric, rather than business- or engineering-focussed.
Visitors use documentation to install, configure, update, and maintain the product. To this end, product documentation should help the reader understand:
What a product does and its key features.
How the product works in general terms.
Which features are most relevant to them and their use cases.
How to install, configure, upgrade, and manage the product.
What product documentation isn't
Product documentation is as much defined by what it isn't as what it is.
Documentation isn't marketing or sales material
Product documentation is complementary to marketing and sales, but it's also distinct from it. Sales and marketing material is designed to convince a non-technical audience to adopt a feature or product; documentation is written to help the reader use a feature or product after they've already decided to adopt it.
This doesn't mean that documentation can't overlap with marketing and sales content, but the purpose, style, perspective, and approach is very different. It's written to help the reader actually set up and use products, not to generate leads or close sales.
Be careful not to disseminate marketing or sales content, such as pricing details, or to repeat marketing or sales language, such as “you can easily share … ”, which can skew user expectations. This sort of language can even be used in litigation centred around how the documentation is interpreted.
Since product documentation isn't intended to actually persuade anyone to adopt a feature or product, people tend to trust it more. That means there's still a wider audience to consider. Product documentation tends to attract key decision-makers, such as PMs and executives evaluating the complexity, size, and cost of implementation –– information that they can’t fully garner from marketing and sales.
To keep this trust, we need to maintain the distinction between product documentation and marketing or sales content. The focus should always be on helping the reader actually use the feature or product, not on marketing or sales goals. Keep everything factual and concentrate only on what's needed to set up and use the feature or product.
Documentation isn't static
Documentation is always evolving, alongside the product.
Don’t include “coming up/soon” content, unless it’s to give the intended audience a heads-up for a major change that impacts how they use the feature or product, how the feature or product works, or its availability, such as something reaching end-of-life by a certain date.
In general, though, don't worry about the future state of the product –– that’s the concern of marketing and sales. Documentation is concerned with helping customers use the product now, in its current state. We can always change the documentation when the product changes. That’s what tech writers are here for.
In aid of this process, we should structure documentation such that it can be updated without impacting the content around it.
Organising information strategically into digestible chunks of information also helps the visitor of your content. Self-contained content allows readers to jump to the relevant information for the task at hand. This content should be ordered and signposted in such a way that readers can orient themselves no matter how they find themselves in the docs set –– not everyone comes through the front door.
Documentation isn’t ReadMe content
Code documentation, such as ReadMe content, belongs to the software itself, and is targeted at other developers to give them a brief but technically detailed description of the software and information about the code.
If it were for a car, it would be written by mechanics for other mechanics working on building the same car. It contains all the technical information and configurations needed to run the software. These technical details, such as API references, copyright details, or upgrade instructions, and basic information about the code, don’t belong in product documentation.
Even if the consumer of your documentation is sometimes a developer, product documentation is written to get the reader up-and-running, rather than to aid communication between internal developers of the software. Thus, the content in product documentation needs to focus on user actions rather than the software itself.
Documentation doesn’t replace technical support or troubleshooting content
Technical support and troubleshooting content serve a different function –– explaining and solving for specific issues, in detail, with suggested fixes. Product documentation complements Technical Support and troubleshooting content by helping reduce the need for it in the first place; it doesn't replace it.
Some product documentation might include troubleshooting information for common problems but, ideally, with good product documentation, users won't encounter issues in the first place. When they do seek to solve a specific issue, targeted and to-the-point troubleshooting content reduces load on Technical Support.
Contacting Technical Support is like calling a mechanic or breakdown assistance. You shouldn't need a mechanic or breakdown assistance for filling tyres that are low in air or to replace windscreen wipers. If we can help people figure these sorts of things out for themselves, Technical Support can focus their effort on cases that do require some hand-holding.
Technical Support might still use product documentation to help customers and to point them to other features that might meet their needs. They can use the documentation as a source of truth and as a shared point of reference to quite literally make sure they're on the same page with customers. Other company employees might also benefit from documentation, using it to keep up-to-speed with product developments.
Documentation doesn’t replace UX
You don't need to list every expected output of every possible interaction, or to document every element in the UI and how it works. Consider, for example, how a search bar behaves. You would expect partial match functionality and for a search to return results after pressing enter without it being documented. If it doesn't work as expected, that's a UX issue.
This is one of the most frustrating parts of product documentation: sometimes it's used as a plaster for a flawed design that you wouldn't need to explain if the UX was better.
On the bright side, the co-evolution of the product and its documentation helps create a feedback loop that can inform future design. For example, if content about a feature gets high traffic, it could indicate an issue with the UX of that feature. This insight can be used in combination with usage data and customer feedback to inform the direction of product development.
The process of writing documentation during product development can even potentially uncover issues with a feature before it's released.
Documentation doesn’t list every component or functionality
Product documentation exists to help users understand what they're doing, why, and how, but not to the point of drowning useful information in superfluous detail.
Product documentation exists to help readers use the product for specific purposes. Aim to write just enough to help the reader get value out of the feature or product. There's no need to steepen the learning curve with details about every component or functionality.
This would be like expecting a person to know how to build a car to pass their driving test; a person only needs to know how to operate the steering system, how to read the symbols on the dashboard, and the rules of the road –– things that are relevant to the task at hand (getting from A to B).
Product documentation as part of the customer journey
It's true that product documentation isn't just used by administrators to install and manage the product.
Prospects often consult it to make a more informed decision about choosing your product over another. Product documentation is likely to come up in search engine results. It can be used by Marketing to find details to put into blog posts. It can also be used by Technical Support to help fix problems. And it can be used by Product and Design teams to inform product development.
Most importantly, though, product documentation fosters user engagement after you've sold the product and started the onboarding process. All other uses are supplementary. The target audience is the consumer. Legal, marketing, product, and troubleshooting outcomes are bonuses, and another reason to make sure you maximise the quality of documentation –– this is what makes it an objective authority.
