How to write technical documentation

Technical documentation is similar to other documentation, but it also has some specific qualities to keep in mind

What to write in your technical documentation

When you’re writing technical documentation, it’s more important than ever to give your readers all the information they need, without adding too much detail. Let’s start with the kinds of sections you should think about including.

Tip: If you’re using an online documentation platform such as GitBook, you can add some of the elements below to your navigation bar to make them easy to access from anywhere — as well as a call to action such as ‘Sign up for free’.

A quick start guide

A lot of visitors to your docs may want a quick overview of what you’re writing about. So explaining what your project does and why you’re working on it is super helpful. I think IONOS does a great job of this, explaining the product in just two lines of text, then linking to a guide for more info.

A sample of your code

If your code is simple but makes a major improvement on an established process, you might want to show that off on your opening page. A small snippet if an easy win — and with a tool like GitBook you can insert a code block, or use an integration to link GitHub code snippets directly into your docs.

// Log "Hello World" in the console
console.log('Hello World');

A link to your code or APIs

Whether people want to browse and contribute to your code, or just want to get started with your APIs, it’s a good example to link to everything your readers might need in one place. Again, in tools like GitBook you can easily link to APIs using API Method or OpenAPI blocks.

For instance — at GitBook we offer an AI Assistant that offers you context-rich information and answers based on your docs content and other sources. The API is documented like you see below:

Ask a question in a site

post

The response is streamed.

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

formatstring · enumOptional

Output format for the content.

Possible values:

Body

application/json

questionstring · max: 512Required

scopeone ofRequired

or

or

Responses

200

OK

text/event-stream

post

/orgs/{organizationId}/sites/{siteId}/ask

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/ask HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 105

{
  "question": "text",
  "context": {
    "siteSpaceId": "text"
  },
  "scope": {
    "mode": "default",
    "currentSiteSpace": "text"
  }
}

200

OK

{
  "type": "answer",
  "answer": {
    "answer": {
      "markdown": "text"
    },
    "followupQuestions": [
      "text"
    ],
    "sources": [
      {
        "type": "page",
        "reason": "text",
        "page": "text",
        "revision": "text",
        "space": "text",
        "sections": [
          "text"
        ]
      }
    ]
  }
}

Installation instructions

Remember — we’re trying to make it as easy as possible for people to get started with your work. Try and explain how to do that in a couple of sentences, and link to a dedicated page of instructions if you need to add more information.

Details for people who want to contribute

You might’ve written your code in a specific way, and want others who contribute to do the same. Write those standards down, and then everyone will be on the same page.

With a tool like GitBook, you can also set up a two-way sync your documentation to a GitHub repo. That way, if someone contributes to your work on GitHub, the changes will automatically sync to your GitBook documentation so everything is up-to-date.

FAQs and support information

There are bound to be questions that a lot of people ask about your product. If that’s what people are searching for, it’s a good idea to address it — either by fixing it, if it’s a bug, or by documenting the question and a good answer. And don’t forget to tell people where they can go to get more help if they don’t find the answers they need.

The most important thing here is keeping your FAQs up to date. Make sure you tweak them when you release an update, or add extra questions if you see users asking the same thing often.

What’s the best format for FAQs?

These expandable blocks are perfect, because they don’t take up a ton of space. Readers can quickly scan to find the answers they need in the list, then click to open the answer. You could even include a few relevant FAQs at the bottom of each page of your documentation to make things even easier for your users.

Licensing information

How are people allowed to use your code? It might not seem important, but if someone wants to use what you’ve done, they need to know the restrictions. Choose one of the common licenses — such as GNU, Apache or MIT — and list it clearly in documentation.

The best technical documentation format

Okay, so I'm biased, but in my opinion the best technical documentation format is a dedicated online tool — like GitBook — that makes it easy to create, structure, edit and continuously update your documentation.

Tools like this are ideal, because they also allow you to sync your content directly with GitHub or GitLab. So you can import your existing content to give you a good basis for your docs, then expand on it using dedicating editing tools, integrations and more.

Of course, you can also write your technical documentation in other formats — a simple plain text page will also do the job, or even a basic Wordpress site. But the best online documentation tools give users a great experience, and offer built-in features like templates, Git-like version control, and customization options.

Gravitee’s documentation is a great example of customization done well

Communicating technical information clearly

Once you’ve chosen your technical documentation format, it’s time to start writing. Communicating clearly is especially important when it comes to technical information — for two reasons.

First, the thing you’re writing about may be quite complex, so being clear will avoid confusion. Especially for people who don’t have as much knowledge as you.

And second, for many people your documentation will serve as a reference for whatever they’re working on. They may be looking for a specific piece of information, or land on your docs from a Google search. And when people are looking for something specific, giving them a succinct, clear answer is just about the most useful thing you can do.

Keep things simple (but don’t leave out important details)

Because of all that, simplicity is essential in your technical documentation. Don’t waste your users’ time if they’ve run into a problem and stumbled on your documentation looking for a quick solution!

Avoid adding unnecessary details. If you have extra information that may be helpful to specific people, like developers, think about adding it into an FAQs section, or insert an expandable section below the main body of your content with the extra detail. That way, people who want it can find it, but it won’t get in the way for people who just need the basics.