Best practices for developer documentation
7 minute read
Organizing your documentation
Present your documentation in a way that it is easy to read and helpful for customers.
Navigation menus hierarchical structure
Clear navigation is highly usable, it helps the user to navigate through your website. Think about what are the main topics that the user will be searching for, and under those, what specific questions or documents they will be looking for.
Organize similar type of contents under the same menu. For example, you can place all Installation and Upgrade manuals under the Installation instructions menu. This makes it easier to find all information related to installation in one place.
More than three levels can make the menu confusing to navigate.
NoteAlthough it is a good practice to have a well-structured menu hierarchy to help users when they are navigating in your documentation website, have in mind that users usually land on a page from a search result. In this case, the order of the menu is not relevant.
Make the documentation discoverable
Documentation is only as helpful as it is easy to find. Include documentation in Google search engine to help users discover the contents and improve the documentation visibility on search engines.
Some recommendations for using search engine optimization (SEO):
- Create short, unique, and accurate page titles
- The navigation of a website helps search engines to understand what content is important
- Follow the recommendations on Use meaningful link text to create link text for URLs
The following sections help to provide and organize more in-depth information in your documentation.
Add a get started
Add a get started section to introduce your product and detail the first steps users need to start using the product.
Add a reference
The reference section aims to document some particular parts of the software in more detail. It should provide the content to support the performance of a task. Its audience are users who are familiar with the software but need more details or a quick guidance. You can add technical references of the software’s code, functions, APIs, CLI, parameters and so on.
- Flow variables reference
- Amazon API Gateway Documentation
- Docker reference documentation
- Kubernetes reference
- Oracle Administrator’s Guide
Add a glossary
The glossary defines all the terms that might be unique to your company or product. In some cases, the user’s understanding of the documentation might depend on the clarity and alignment of specific terms.
Tutorials are lessons that walk a reader through a series of steps to complete a procedure. A tutorial shows how to accomplish a goal that is larger than a single task.
Add how-to guides
How-to guides assume that users already possess some basic knowledge of features, tools, and of how to perform simple tasks. They help intermediate or experienced users to solve a real-world task using the software.
Producing a video is a lengthy and costly task. Videos can get obsolete very quickly, specially when you show screens.
Nevertheless, in Axway, we’ve been receiving more and more feedback from customers asking for videos to help them to use our products. Hence, it is worth adding videos to complement complex procedures, where they can guide and help the user to progress and be successful when trying to accomplish a task.
Code samples and scripts
Code samples and downloadable scripts help the user to get up and running fast. The code must be followed by an explanation on how to use it to achieve a goal.
Add code samples
Code samples are small snippets of code to help the user to understand a concept previously explained. They can also be used to demonstrate the syntax of attributes or parameters.
Add downloadable scripts
Provide code examples in a way that customers can copy and paste and try out your product. The sample could also be downloadable, which is less error-prone than copying and pasting.
- A Sample: Array of JSON Documents.
- You can find a few example schema files in Autopilot Templates repo on GitHub.
Review your work
Quality documentation must be continuously reviewed and improved.
Delete dead documentation
Old, outdated, non-used guides can misinform and slow down the user experience with your product. They can show results in the search, which are not relevant or correct anymore.
Do not duplicate information
Duplicated content creates inconsistency and frustration, and it is hard to maintain.
- Record the information once where it enhances the work the most
- Link to information about a common technology or process instead of rewriting it in your own words
Follow these guidelines to make your content more concise and clearer.
To determine the appropriate length for you page consider the following:
- Keep all required information to complete a task in one single page, so users don’t need to jump back and forth between pages to achieve their goal
- Users don’t have to scroll all the way up or down the page to find information, they can use a right-side menu (like the one used in Axway open docs pages) to navigate the content
- Having all related content in one page makes it easier to find information with a
Find a balance between no documentation and excessive documentation.
- Make documentation skimmable to help users find the content they need quickly
- Action-oriented headings (strong, clear verbs)
- Remember that users scan in F-Shaped pattern
- Break up the text often
- First 3-5 words of every paragraph are the most important
- Use bullet lists
- Use variations in typeface (links, bold, etc)
- Use code snippets
- Use screenshots sparingly
- Use animated gifs
Use meaningful link text
Effective link text helps the user to understand where each link leads and decide whether they want to click the link or not.
Observe these guidelines to improve user experience and accessibility.
- Do not paste the actual URL in the page as this does not read well, specially for screen readers (accessibility)
- Do not use Click here, it is bad for SEO and does not describe the target
- Use meaningful words or phrases in the link text for URLs to better represent the content of the destination
Do not overuse tables
Not all analyses or results warrant a table or image. Some simple results are best stated in a simple and short paragraph.
Tables can be used as quick references and can reveal trends, patterns, or relationships that might otherwise be difficult to grasp in plain-text format. They permit rapid access to and relatively easy comparison of information. Overly complicated tables may be difficult to understand, so strive for simplicity, for example, table cells with single paragraphs. Complex tables can be a challenge for adaptive technology users (users of screen reader software).
Do not overuse screenshots
Screenshots are hard to maintain, and if they aren’t up to date they can be misleading.
Too many unnecessary screenshots can also clutter the page.
If you can present your results clearly in a few short sentences, or in a list of steps, this means that an image is probably unnecessary.
- Core Practices for Agile/Lean Documentation
- How to write documentation for users that don’t read
- Chromium Documentation Best Practices
- A Guide to Writing Your First Software Documentation
- Why a format of your technical document matters
- Why agile teams should care about documentation
- Search Engine Optimization (SEO) Starter Guide
- I’d Rather Be Writing, API glossary
- Developers Google, Link text
- Writing effective link text
- Infinite Scrolling Is Not for Every Website
- Web Style Guide, Page length
- DITA Reference topics
- Data vs. Layout Tables
- Read Me First! A Style Guide for the Computer Industry (pdf book)
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.