You have achieved continuous deployment for your application – but how can the user documentation possibly keep up?
In recent years, software product development has accelerated, cycles have compressed, and updates are more frequent. You know you still need the documentation to meet regulations, inform customers or reduce support costs. But how can you possibly keep the product documentation up-to-date?
By investing in a content strategy, and planning your product and support documentation, you can take advantage of the content already being produced, automate workflows, and prioritise content to ensure your customers have access to the information they need, when they need it, and how they want it.
Traditional approaches simply won’t work
It used to be that the gap between the type of manual used to support a physical product and a software product was small; both would involve information organised into ‘documents’ and published in PDF format, but the physical product manuals would actually be printed out. That gap has grown to mean traditional approaches are even less useful for software than they used to be. With physical products, the printed documents have become smaller as more content has moved online, but with software, the way the product itself is packaged and deployed has changed significantly, and that means the way the ‘manual’ needs to be built and deployed has to change as well. Now that products are increasingly delivered digitally, the product documentation should be delivered digitally too. So, how have the approaches to software documentation changed?
New approaches - that have their own risks
In software development teams, there are three approaches to creating the content that have emerged to try to align the production of the ‘manual’ with the production of the ‘product’:
- The content is written by the developers or product managers
The people who are creating the product are the ones who know it best, so surely 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 that they are creating and not the needs of the users. And they are usually terrible writers! Over time the documentation becomes disjointed, with different writing styles, making it difficult for users to fully exploit the product.
- The content is generated automatically
Automated documentation tools extract comments and code snippets from the source code and compile them into a document or a set of HTML pages. The more sophisticated tools also provide emulators that allow applications, usually APIs, to be tested from within the documentation. This approach is great for providing a comprehensive list of the application features – but that only addresses part of the requirements. To be useful, documentation also needs to include information such as conceptual overviews, how to access the product, regulatory information, troubleshooting issues, or non-functional specifications.
- The content is only produced when customers ask the question
“Nobody reads the documentation anyway!”, 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 that are 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.
On the surface, these approaches seem to streamline the process of creating content, but they quickly lead to unusable information. With the emphasis on creating the content, the documentation becomes bloated with out-of-date information, leading to customer confusion. These new approaches focus on How the documentation is created. But forget to address Why the documentation is needed in the first place. So what gets produced ends up failing; frustrating your customers and wasting your resources.
How to ensure product documentation keeps up with continuous deployment
When starting product development, you wouldn’t just let the engineers pick the cheapest development-tool stack and let them loose on the code. This would lead to chaos, an inconsistent product, and a product that doesn’t meet the customers’ needs. This is why you have a plan, an architecture, a roadmap, coding conventions, and governance models. The product documentation is no different. The key to improving documentation is planning – this starts with a robust framework; a Content Strategy.
A Content Strategy defines the scope and type of information required by all the product users to help the customer get the most out of it. For example, purchasers need specifications, administrators need integration details, users need tutorials, support teams need FAQs, and developers need API docs. With a Content Strategy in place, you can be sure that the goals of your product documentation are met. If you have a Content Strategy that has addressed the Why, you can look at How you can produce your documentation, confident it will actually work.
How a Content Strategy improves scalability
The Content Strategy gives a clear framework which makes it easy to identify the necessary content and to ensure it is created – regardless of who is responsible for creating it. This enables you to take advantage of the following techniques to:
- Minimum viable documentation
With limited time, you need to focus on the essential content. The minimum viable documentation is the key pieces of information required for each audience to be able to understand why and how to use a new product or feature. More scenarios can be added later in response to customer feedback.
- Make the most of what you already have
If you rely on a dedicated documentation team to create all your content, they will become an avoidable bottleneck. You almost certainly have useful content being created elsewhere in the business.
Product information is being created throughout the product development process, for example, user stories, system architectures, code comments, marketing material. This information can be reused by incorporating it into the Content Strategy. You can then make sure the information is created in a style and format that can be easily incorporated into the product documentation as part of the process.
- Automated code documentation
The comprehensive list of features provided by automated code documentation can be a key 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
By having a clear overarching strategy for the product documentation, it’s possible to give someone responsibility for managing the content. This ensures the product documentation continues to achieve the goals.
Summary
To adapt to shorter development cycles, many teams focus on streamlining How they produce their product documentation to reduce the time needed. This approach usually means the quality, and therefore usefulness of the information, is compromised. And the primary goal of Why the product documentation is needed is not achieved. By putting in place 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. As with your development process, achieving rapid and frequent delivery while not compromising quality requires upfront planning, the appropriate tool chain, and well-defined processes. But once you have these in place, you will have the platform from which to start driving down support costs and increasing adoption rates.
Doing this on your own might sound like an insurmountable hurdle. However, there are different options from advisory support to outsourcing individual process steps to external experts or even outsourcing the entire process. All depending on your internal expertise, skills and resources.
