Content Strategy for Software Documentation
by Bradley Nice, Content Manager at ClickHelp — all-in-one help authoring tool
Every process concerning software product development has accelerated in recent years. That’s great for the consumers, but you still need the documentation to meet regulations, inform customers or reduce support costs. There is a challenge to keep the product documentation up-to-date.
Product and support documentation planning can help you take advantage of the content already being produced, automate workflows, and prioritize content to ensure your customers have access to the information they need.
Before, there existed manuals to support both physical and software products. They were published in PDF format and printed. Such an approach to documentation has become almost useless for software.
The printed documents have become smaller as more content has moved online. Still, with software, the way the product is packaged and deployed has changed significantly, which means the way the ‘manual’ needs to be built and deployed has to change. Now that products are increasingly delivered digitally, product documentation should be provided digitally too. So, the approaches to software documentation have changed.
- Developers and product managers write documentation. It’s only logical that the people who create the product know it best, so they are best placed to write the documentation, right? In theory, this speeds up the process by removing the step of using a specialist to create the documentation. However, as well as diverting your most valuable resources from what they are good at, they tend to focus only on the features they create and not the users’ needs. As a result, over time, the documentation becomes disjointed, with different writing styles, making it difficult for users to fully exploit the product.
- Automatic generation of the content. The automated documentation tools can extract comments and code snippets from the source code and compile them into a document or a set of HTML pages. This approach is great for providing a comprehensive list of the application features — but that only addresses part of the requirements.
- As required by the customer. You are sure nobody reads the documentation, so why not just write and publish something when a customer asks a question and remove the pre-release documentation process altogether? Many support teams faced with customer questions respond by populating a knowledge base with FAQs each time a question is asked. This approach does not provide coherent information journeys, for example, getting started or misses key regulatory requirements. And over time, the knowledge base becomes bloated with out-of-date information.
These approaches have something in common — they quickly lead to unusable information because they focus on HOW to create the content. This way, the documentation becomes overloaded with out-of-date information, leading to customer confusion. But the question should be, WHY do you need the documentation?
For continuous success, product documentation should be taken as seriously as product development. The key to improving documentation is planning — this starts with a robust framework; a Content Strategy.
The Content Strategy determines how much information is required and what type it should be. For example, administrators need integration details, users need tutorials, support teams need FAQs, and developers need API docs. If you have a Content Strategy that has addressed the Why, you can look at How you can produce your documentation, confident it will work.
The Content Strategy gives a clear framework that makes it easy to identify the necessary content and enables you to take advantage of the following techniques:
- Minimum viable documentation
The minimum viable documentation is the critical information required for each audience to understand why and how to use a new product or feature. That’s great when you are limited in time. More scenarios can be added later in response to customer feedback. - Utilize what you already have
You certainly have valuable content being created elsewhere in the business. Product information is created throughout the product development process, for example, user stories, system architectures, code comments, and marketing material. Use this information by incorporating it into the Content Strategy. - Automated code documentation
The list of features provided by automated code documentation can be a vital part of the documentation — but it is not the only part. By incorporating these sections into the Content Strategy, you can ensure that the developers’ comments are consistent and missing information is addressed. If your tools also provide emulators that allow applications to be tested from within the documentation, this can be an added benefit for customers. - Product document management
With a clear product documentation strategy, it’s possible to appoint a person responsible for managing the content. This ensures the product documentation continues to achieve the goals.
By implementing a robust Content Strategy for your product and support documentation, you can take advantage of existing information assets and automation to reduce the overall cycle time while still meeting the documentation goals.
Have a nice day!
Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors
