Good developer experience is a must for the suite of dev tool startups, one of the core pillars to this is good documentation. This blog aims to summarise what good documentation looks like and what you can do to get it. This post will focus on end user documentation for products.

What is it?

Technical documentation explains informations about your product. It needs to be clear and to the point. No fluff.

Documentation is a must for people to use dev tools as without it people won’t be able to use for dev tools effectively.

It falls into four different categories.

  1. Tutorials
  2. How to guides
  3. Technical reference
  4. Explanation

They each resolve a different problem.

  1. Tutorials: allow new users to get started
  2. How to guides: show how to solve a problem
  3. Reference: succinctly describes the machinery
  4. Explanation: allows deep users to understand the machinery

How to write tutorials (onboarding)

Tutorials are lessons that take the reader through a series of steps to complete a project. They should show to a beginner that they can achieve something with it.

Here are things to consider:

  1. Allow the user to learn by doing something practical
  2. Get the user started
  3. Ensure that the user can see results immediately
  4. Have concrete actionable steps
  5. Don’t explain anything unnecessary

How to write “How to guides” (how)

These are specifically goal oriented. Think of it like a recipe. They’re different to tutorials:

  1. Tutorials focus on what you want the beginner to know
  2. How to guides focus on resolving a problem

Heres what to consider:

  1. Must resolve the problem
  2. Don’t explain concepts
  3. Well named

How to write references (what)

These have a single purpose: to describe. So just describe and be accurate.

How to write explanations (why)

These focus on helping users understand. What is the bigger picture?

Here’s what to consider

  1. What is the context? The why?
  2. Don’t instruct. Just discuss and explain.

What makes documentation good?

Focusing on the user and their problem. Work back to resolve the user story problem.