funkyfrogstock - Fotolia
Top software documentation tools and how to use them
The best software documentation helps frame development projects and improve existing offerings. Learn the ins and outs of popular software documentation types and tools.
Companies that produce software invariably face the question of how to publish its documentation. No easy answers exist. Many software documentation tools are available, but there is no clear leader. There are standards for how to create software documentation pages, but even that common ground does not solve all problems.
I write documentation for software companies on a weekly basis, so it's a struggle I know all too well. Here are insights into reference and guide software documentation types, the things to look for in documentation tools, and the popular tools on the market from SwaggerHub to ReadMe.
Software documentation types
People in many roles, from a cloud services salesperson to an internal software developer, need to host written material for users, probably using some software documentation tools for the job. To understand the options, let's begin with a question for software developers specifically: How should a company document APIs and SDKs?
APIs and SDKs are two kinds of software products that developers write for other developers. APIs act as front ends for software and users to interact with your software. An SDK provides a set of tools with a unique purpose. For example, to create a screen on an Android device, you use the Android SDK to tell the program the screen orientation, the mobile device type, colors, etc. We'll use APIs and SDKs to run through the software documentation types available, and how to use them.
References. References give the technical parameters for how to use objects, methods and functions. They don't provide tutorials, just the specific information needed to make them work. References are tersely worded, which can make them difficult to understand.
The standard for documenting APIs is called the OpenAPI Specification (OAS) (formerly known as the Swagger specification). OAS automatically generates reference documentation, and it can include code examples in different languages. But a programmer must spend countless hours filling out OAS definitions. To justify the amount of time spent on OAS definitions, some organizations have adopted the descriptions as an architecture tool to generate boilerplate code to start off development projects.
Another standard, specific to Java, is called Javadoc. Javadoc requires slightly less effort than OAS, but the reference documentation it creates is so complicated that programmers tend to prefer guides instead.
Guides. Developers write guides to explain how to use the SDK or API. Unlike references, a guide is a free-form narrative. It does not follow a fixed format, but is typically written in paragraphs with illustrations, tables, lists and charts. Guides provide background material and code examples, define concepts, and explain parameters and returned values.
A guide goes into greater detail about the parameters needed to use the software than a reference does, and it provides links between sections to help the user find related information.
10 features of good software documentation tools
It's easier to create various types of software documentation -- for various types of software -- when you have the right tool. Good documentation can even make a product better over time. Look for tools with these features:
1. Markdown and HTML support. Software documentation tools that support both markdown and HTML are preferable. Markdown is a common standard for software documentation; it's essentially a plain-text, abbreviated form of HTML, which can be too wordy and awkward to use to write manuals. Markdown generally works for writers who want HTML-like text modifiers to make lists, tables and more. Also, Markdown imposes limitations; you cannot change fonts or put borders around objects, for example. So, the ability to mix HTML and markdown is helpful.
2. Feedback. Feedback makes software better, and documentation tools have various options to collect and review feedback. Everyday product users will discover features you never thought of -- I've had users contribute entire code examples. These users will help uncover errors in your site and ask clarifying questions. Some tools connect software users and developers over email, or with a question button for comments. ReadMe, a popular documentation tool, lets users check out pages and make changes to them. Those changes are then put into a queue for developers to approve, reject or merge with other changes.
3. Custom, cloud-hosted domains. There's no need to host your own product documentation. For example, with ReadMe, start with a domain like your-product.readme.io. Then, when you are ready to publish the domain, change the path to documentation.yourcompany.com and add a DNS record to point it to ReadMe.
4. Access control. You won't have a single writer contributing all documentation on most software builds. Writers from different roles and levels add information, so look for a tool that provides access management.
5. Click-button APIs. Make it easy for your users. Your choice of tool should enable users to click a button to run APIs directly from the documentation.
6. Client-side backups. Software documentation tools should let you create your own backups. Don't depend on someone else to back up your system.
7. Technical support. Some tool vendors provide meager support. Find a vendor that will respond when you get corruption in a page or that can help you to recover something that is lost. ReadMe gets a low grade in this respect, at least with developer accounts; ReadMe Enterprise might offer better support.
8. Customizable landing pages. Ideally, a software documentation tool will let you use both HTML and style sheets on landing pages.
9. Table of contents. Documentation tools should enable you to set a clear table of contents for easy navigation.
10. Publishing control. You should be able to publish and unpublish pages as needed.
Software documentation tools
Now that you know what to look for, let's explore software documentation tools. I have worked with many software documentation platforms, many of which are focused on OAS/Swagger. OAS limits users to reference docs, though tools expand on capabilities.
Here are some software documentation tools that are guide-focused:
- ReadMe
- Apiary
- Stoplight
- APIMatic
- SwaggerHub
- Read the Docs
- GitHub Pages
ReadMe might be the best option because of its ability to handle both OAS references and guides. However, its recent platform upgrade and slow developer-level support took some getting used to. Ultimately, with few choices in the software documentation market, you should adapt and stick with any option that serves your needs. Here are a few pointers on three popular options.
SwaggerHub. SwaggerHub, a SmartBear product, is a good option for learning about Swagger and OAS, as well as hosting documentation. SwaggerHub includes a specification editor to write OAS specs.
SwaggerHub provides a demo site called Petstore with a YAML editor. With OAS, you document every endpoint, method, error code, parameter and object in either YAML or JSON formatting. Thus, the Petstore editor includes endpoints like POST to add what's called a pet. The site lets you try out endpoints, enter parameters and authentication information, and then run APIs.
ReadMe. I've worked with ReadMe more often than with any other software documentation tool. I recommend this file format for free-form guides. ReadMe does a nice job with manually created APIs and those auto-generated from OAS. With a stable product and wide base of users, it's easy to overlook ReadMe's aforementioned shortcomings.
To get started, ReadMe asks for your product name and whether you are documenting a REST API or something else. It also asks for a temporary domain name, which you will later switch to your existing domain. After you provide that information, you are brought to the main page. Here you can create guides, work with OAS, write reference material and customize the site.
If you indicate that you will use OAS, ReadMe will ask you for the URL where those specifications are stored. ReadMe takes those specs and auto-generates documentation and code examples. You then put in the static part of your API definition, like the main URL, and what kind of credentials you want to use, such as OAuth or a secret key.
For guides, you work with the ReadMe editor. You can type markdown directly into the editor, or use widgets to create markdown objects. On the screen below, you can also access support for HTML underneath the widgets by clicking View all.
GitHub Pages. GitHub's support for markdown helped make it a standard for hosting application code. Most open source software is stored in repositories on GitHub, including well-known projects like Elasticsearch. Each program starts with a landing page written in markdown called README. Take the example of Elasticsearch, and its README page. GitHub, however, is not a good platform for software documentation. For example, GitHub does not generate a table of contents. To have one, users must manually upload images to a folder and then create links to them. Other products handle this task more easily.
Several software projects write their own front end to GitHub. These projects will work in a tool like Jekyll, which can generate HTML from instructions on GitHub pages. This approach combines markdown with special markdown-like syntax, which is not ideal.
