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.

  • 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:

  1. 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.
  2. 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.
  3. 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

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Bradley Nice

Content Manager at https://medium.com/level-up-web 👈. I write about web design, web development and technical writing. Follow me on Twitter and Facebook