5 Steps to Make Great Technical Documentation

So, you’re making a software product. An important part of creating, selling, and maintaining it is documentation. With the right software for technical documentation, you can save a lot of time on routine operations. However, it’s not the software that makes the right documentation but your content-making abilities. These are certain steps to create documentation for both the developers’ team and the customers.

The following recommendations are equally effective for making help files for customers and for, say, writing guidelines for designers, coders, writers, and other professionals working on the project.

1.  Make a Plan

Technical documentation is more than plain helpful files. It can be used for marketing, crowdfunding campaigns, social advertising, whatever. This wideness requires you to plan what you are writing first.

The questions include:

  • The content. What should be covered? Of course, the fuller the better, but there is always some reasonable margin.
  • Who are these docs for? Your colleagues, or customers, or potential investors? This defines both the style and the message. Choose the language: the most common – for customers, the most efficient – for developers, and the most salesy – for commercial needs.
  • Which tools do you use for that? It matters because some tools require time to master them as well.
  • Do you know the material perfectly? Otherwise, it will take some extra time for researching not only your product but alternatives and the market situation as well.
  • When should the documentation be ready? It also includes the schedule of documentation updates (that caters to the product updates).

We know that Agile and Waterfall approaches have different requirements as for plans. But even if you prefer Agile to preplanned Waterfall, you still need an initial plan rather than the stream of consciousness.

2. Design and Draw

A good novelist does not just write the text as they go (unless they follow the stream of consciousness, which is not our pattern). They plan what happens along with the storyline, structure the novel in chapters, write plans for each chapter, and then adjust the plan if necessary. It works the same way with technical documentation.

While texts are always texts, the table of contents and the hierarchy of one should be of the greatest concern. Luckily, there are many templates that already offer a hierarchical approach you may embrace, with few or no changes.

Typical pages are good for the project. Use schemas for creating them, which makes writing easier too. For example, a page can look like this:

  1. Title
  2. Subtitle. The basic extra information
  3. Overview. The announcement of the page content
  4. Table of contents within the page
  5. Sections, according to the table and explaining the subject
  6. Media (pictures, videos, audios)
  7. Read next
  8. Related pages (along with links within the text)
  9. Support (reporting to the support which page they are contacted from)

3. Write!

Of course, it does not only take writing texts. Taking screenshots and marking them with highlights, arrows, zooming, and so on, is just as important. Visuality is often better, and words just grant you see what you see. Often it takes an animated picture or a video to show a process rather than its separate stages. But we will call all the content “texts,” if you don’t mind.

Hyperlinks are necessary. It’s a fast way to navigate to related sections instead of going back to the table of contents and searching for them manually. But don’t make most of the text blue (instead so many links are really needed). Be careful with external sources: they can change without your notice. If the information on the page is static, it might be better to copy it. If not, you better check the links periodically to make sure the pages you address are still where they were.

4. Test!

Testing the documentation takes some stages, as well as testing any software. The most important elements of testing include:

  • Both the facts and the grammar should be correct.
  • The texts should be written in such a way that even a reader with no related experience at all can understand them.
  • No section of the product should remain uncovered.
  • Not only should the text be written in the same manner throughout the documentation. The reader that goes through links to read multiple related sections should not sense the transition at all. That means links should lead to certain fragments answering the arising questions. Not only should they lead to the right pages, but to the right paragraphs within these pages as well.

In addition, testing should ensure the design is right. Is the documentation readable? Are there the right fonts? Does the reader recognize the style immediately when returning to the tab? When the reader should focus on the content, the design should not attract too much attention; it has to highlight the content while helping to make the right perception in the background.

5. Maintain and Update

The most important thing about software products is that they are (in the perfect world) never finished. They constantly evolve, as the developers fix bugs, refine the interfaces, implement new features, make versions for new platforms, and so on. Neither is the documentation ever completed. It should evolve with the product.

It’s a consensus now that the best way to keep software documentation is online, rather than include HELP files in the installer. First, these files are too easy to lose and delete when stored locally. Second, they cannot be updated when the new version is released. When you offer a link to online help, these problems are solved automatically: the pages are always there, and they are always the latest. Stop… Are they? Can it be so simple?

Yes, for the user, it can. But for the staff, it means site maintenance that ensures its constant functioning. Along with technical aspects, it means content updates, so the documentation is relevant to the version the user has run. It means that if your product exists in multiple versions, there should be multiple versions of documentation as well, each available from the relevant version.

Step by Step

While each of these steps can (and must) be split into more subtasks, these parts are much easier to do when you already have a strategic view of your work. So keep in mind (in the background, but nevertheless) the result you want to get. There is nothing wrong with intertwining or returning to earlier steps when necessary. Just keep the process going.

Have you learned anything from this article? If yes, why not share it with your Facebook or Twitter readers? Maybe, they will benefit from it too. If you have something to add, our comments section is already expecting you.