Create product documentation

Contributors

@jamaicawinshipgmail-com @andreea-macoveiciuc-content-expert @danielisler1gmail-com


Business Benefits

Increase user satisfaction and retention by satisfying customer expectations.


Use user insights and testing tools, such as FullStory, to understand where users are struggling to determine where more product documentation would be valuable.

Identify where your product is intuitive and where users get confused. You can also use what you know about your target audience to understand how and where they are likely using your product, and what they expect in its documentation.

For more guidance, talk to your customer service team to learn where customers are having the most issues with your product.

Make a documentation plan by defining the goal and format, and gathering resources.

To define your goal, consider:

  • What do you want the reader of the product documentation to be able to do?
  • Who is the reader?

Format options include physical documentation, PDF, or website page. PDFs and website pages allow for easy navigation through links. Some audiences prefer a physical copy as well.

Create the structure and outline of the documentation, including a navigation structure, design template, and content outline.

Most product documentation should contain:

  • A title, subtitle, and overview per page or topic.
  • Navigation structure with hierarchies of categories and subcategories.
  • Table of contents that matches the topic titles.
  • Text and images.
  • A way to provide feedback or ask for more help, like a ranking system, contact link, or a customer service phone number if it’s physical documentation.

For example, Unbounce’s product documentation has a navigation structure that contains a clickable table of contents, related articles, search bar, and a page overview with internal links that jump to the appropriate section. There is also a reply meter at the bottom of the page so that readers can easily rank how useful the documentation was.

Draft the content of your product documentation using language that fits your target audience.

Best practices for product documentation writing:

  • Write concise, clear titles, like Set up your domain, instead of blog-style titles like 3 Must-Try Ways to Set Up Your Domain.
  • Keep explanations as concise as possible while still providing all necessary information.
  • Include all steps, even if they seem obvious to you.
  • Tailor language to your target audience. For example, if your product is used primarily by a non-technical audience, avoid technical jargon.
  • Always define acronyms before using them.
  • Avoid words like just or simply because they can seem patronizing.

Use both words and images throughout documentation to aid different learning styles.

Screenshots, images, videos, and graphics can simplify concepts that would be difficult to explain through words alone. For physical products, include a link in the documentation to videos on your website that demonstrate the various ways to use your product. Examples of companies that do this well:

Edit, revise, get peer reviews, and test your product documentation.

Your editing process should include:

  • Peer edits to catch errors, ask for clarification, and spot areas that need improvement. Ask people who know how to use the product already and people who don’t know about the product.
  • Remove unnecessary words and clean up complex phrasing.
  • Proofread.
  • Safety check to ensure instructions cannot be misread in a way that is dangerous to consumer.
  • Navigation walk-through to ensure navigation ease.
  • Usability tests.

Publish your product documentation in places that are easy for customers to find.

To help people find the product documentation:

  • Create a separate webpage for it within your website so that it comes up in search results.
  • Link to the documentation at multiple touch points, including onboarding email, the product page, and in website navigation bar.
  • Make sure your customer service team knows where it is.

Create a schedule and plan to update and maintain documentation.

Assign someone to the maintenance role. Set time frames for periodic maintenance and reviews, such as once every 3 months, 6 months, or a year. If there are changes made to the product, this person should be notified and make appropriate updates to the product documentation.

Last edited by @hesh_fekry 2023-11-14T11:07:45Z