Best practices for developer documentation

Follow these best practices when developing Axway product documentation.

7 minute read

Organizing your documentation

Present your documentation in a way that it is easy to read and helpful for customers.

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.

Example:

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

Writing documentation

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.

Example:

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.

Example:

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.

Example:

Add tutorials

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.

Example:

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.

Example:

Add videos

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.

Example:

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.

Example:

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

Writing style

Follow these guidelines to make your content more concise and clearer.

Page length

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 Ctrl+F search

Be minimalist

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

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.

Reference articles