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.
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?
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’:
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.
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.
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:
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.