Software Documentation describes how a software can be used and should be operated. The term Documentation Tools describe the software or application that can be used to create and manage the software documentation.
Why is software documentation important?
It helps the user and customer of a software using the product.
It helps the developers and support team of the software to provide all necessary information in one place.
Documentation can be split in the following groups of documentation
- Internal Documentation – with requirements that describe all the features and attributes of the system, before the development phase; architecture design documentation that describe the plan and the status of how the software product is being implemented and developed by the developers; technical documentation that is mostly written by developers an contains e.g. source code, api documentation and code snippets.
- External Documentation or User Documentation, that is consumed and read by the users and customers. These documents include for example a knowledge base or the release notes of the software product.
What is the best way to write software documentation?
The process of generating software documentation can be summarized with the following steps:
- Identify the persona and user groups. What groups of customers will be in contact with the product during the life cycle? For b2b-software products this also includes operators and IT department, manager roles and the users of the product itself.
- Brainstorm about necessary information: What are the shared use cases and requirements? What information is necessary to get their jobs done? Is a process documentation necessary?
- Select the relevant documentation types that are relevant for each of the persona. In the beginning this list should be short and might be extended over time. Maintaining many different documentation types is hard work, since every new release needs an update of the underlying documentation. This list might include a user manual, knowledge base and release notes.
- Think about other restrictions and requirements of your customers and product: Do your customers speak different languages – than a multilingual documentation is necessary. Should the documentation be available to the public, or only to paying customers (= restricted, private user documentation)? Should the documentation be included in your product?
- Depending on your specific requirements, you might need to evaluate a specific software documentation tool or start with a simple tool as Microsoft Word, a CMS as WordPress, or MarkDown hosted on github. Process documentation tools or a specific document management software might be necessary if you e.g. need to maintain a multilingual knowledge base or a private, password protected documentation hub.
- Create the necessary documentation, mostly done by a technical writer.
- Review the generated documentation internally by the different departments – product management, support and maybe event marketing and sales.
- Publish the final documents in your documentation system and inform your users.
What are software documentation tools?
There are many tools and software products that can be used to create outstanding software documentation:
- Text-based tools as a simple text editor, Microsoft Word or Google Docs. Easy to use, simple and provide a fast result to edit plain text and structured (e.g. mark-down) files.
- Desktop applications that are installed on the computers of the developers or technical writers, e.g. ClickLearn
- Specific tools as e.g. a process documentation software, project documentation software as Microsoft Visio
- Online documentation software that can be further divided into documentation software suites that might even include support and chat functionality, or specific tools for the different documentation types as e.g. a knowledge base software or process documentation tools.
What other programs and applications are necessary to generate great software documentation?
Writing and hosting the end-user documentation is the main part. Addition software tools are necessary to create outstanding end user documentation. Some categories are
- Screen Recorder – list of free and commercial screen recording tools for Windows, Mac, Linux, Mobile and Browser
- Screenshot tools
- Improve writing style as e.g. Hemingway Editor
What is a good web-based tool for software documentation?
There are different doc tool products on the market which is evolving and changing daily.
Atlassian Confluence is one of the leader when it comes to web-based software documentation. It is wiki-based and provides a lot of features. It can be quite complex and challenging to master. Targeted mostly for enterprises and bigger companies.
Zendesk Help Center is a knowledge base and part of the Zendesk product suite for support teams and departments.
ReadTheDocs is a doc tool and provides a solution for developer-centered documentation generation. It is free for open-source projects (showing Ads) or paid for commercial products.
Github Pages can be used to generate and host markdown-based documentation sites for free.
Where can you find good examples of website documentation?
What makes a good software documentation website is hard to measure. It should be user-friendly, specific to the requirements and use cases of the product’s users and of course easy to read and understand. The range of documents should be relevant and should include e.g. user guides, a knowledge base and – if appropriate – a full-fledged API documentation.
Hubspot Help Center provides a wide range of documentation types as e.g. a knowledge base, academy (with videos and certification), customer blog, community and developer documentation . It is multilingual with translation e.g. to Japanese, Spanish and German. A glossary describes the typical “hubspot keywords”.