This document is aimed at detailing the best practice in view of keeping product documentation updated with ongoing product changes.
Before explaining the best practice itself, it is useful to define what product documentation is. This kind of documentation describes the product that is being developed and provides instructions on how to perform different tasks with it. As a technical writer, first of all, it is important to choose a software documentation tool to deliver such documentation to your users; that tool can be GitHub.
As a product company, Qu Beyond is constantly releasing new features. Consequently, there is a need to iterate on versions of the product or features, and it is highly essential to keep track of the different versions regarding the documentation. This can even mean creating entirely new knowledge bases and maintaining several knowledge bases for different versions of the product. For that reason, as a technical writer, you should use a tool which allows you to create different versions of your documentation and even switch between them in the editor, like Helpjuice, Salesforce Service Cloud, or other. Keeping track of your documentation tasks in collaboration tools like Jira, Trello or Azure DevOps (board) is also essential.
Tools like GitHub allow you to work in Markdown and, generally, it is necessary for technical writers to be able to use markup languages, like Markdown. One of the advantages of working in a lightweight markup language is that content can be easily styled and presented in a visually appealing way. Besides, if you need to migrate your content over to a different system (already written in markup), then you can keep all the formatting in your content.
- Using links and anchors. This will contribute to make the document easier to read and search as readers will be able to understand the information gradually. For instance, you can provide links to customer interviews and anchors to previous discussions or other external information related to the project.
- Including images. People are more likely to perceive information by looking at the images than reading an extensive document. Different visual models will help readers to easily understand and get the main idea of the document in a more effective way than reading lot of paragraphs.