How to Make Documentation Easier to Read

If you ask questions that one can quickly answer with the documentation, people's reactions will depend on the atmosphere of the place in which you ask, the team you work with, or the online forum. The friendly ones will give you links to where you can find your answers. The less friendly ones will provide you with “RTFM”—Read The *cough Friendly* Manual— or give you a link to Let Me Google That For You.

You should try avoiding that. Let’s see how you can develop the skill of reading documentation!

Documentation: Use it

Most importantly, just start trying to get your answers from the documentation as you struggle with things. The most significant advantage of reading the documentation is that you’ll often find your answer there. You just need to dive into it and find it on your own. As you progress in your career, you will find more and more problems, there is no ready-to-follow tutorial.

Find the Solution to Your Problem in the Documentation

Most documentation is relatively dry and meant to provide answers, and it’s not necessarily engaging to read. It’s much easier to focus on it while looking for a solution to a problem.

I hate reading documentation to learn about the project. It doesn’t matter if it’s a new project I’m starting on or a library I’m learning about. It feels like a waste of time because I have no context, and it’s difficult to understand the connections between the things I’m reading about.

Instead, I would try doing something on my own, fail, and come back to the documentation looking for an answer. In that case, I at least know what I don’t know, and I’m keen on bridging the gaps.

Use Search Tools in Documentation

You can use search tools to quickly get to the relevant information when you have a problem to fix.

In the case of third-party libraries, you can utilize search engines to limit the search to the project website by adding site:<domain>:

It works the same using Google, Bing, and DuckDuckGo.

For in-code documentation, you can use the same tools you use for searching through the codebase:

• in-editor search
• ripgrep
• or git grep

An example with git grep:

$ git grep 'http\.post'
src/auto/injector.js: *          $http.post(trackingUrl, trackedEvents);
src/ng/http.js:     *   $http.post('/someUrl', data, config).then(successCallback, errorCallback);
src/ng/http.js:     * - {@link ng.$http#post $http.post}

Searching through the doc has a few benefits:

• you can familiarize yourself with the documentation structure
• you will find all parts of the documentation related to your topic

API reference - dry description of methods

Tutorial or guide—it provides more context.

Don’t Worry If You Don’t Understand the Documentation

Documentation quality varies a lot. Often it’s not a very accessible document. It could be that there is an assumption that a reader has some system knowledge, and it’s not explicitly stated in the text. This leaves the newcomers a bit lost.

The most problematic can be closed-source, commercial projects. If you have a small team maintaining both the codebase and its documentation, it can be months between any new set of eyes going through the docs and trying to make sense of it.

Open-source projects are usually slightly better. The ones without good documentation are less likely to succeed.

Don’t Skip the Guides

If the project provides a tutorial or guide, it can be a good idea to check it out. If you struggle with a similar issue often, just find a part of the guide that covers it and go through it. A well-done guide will provide you with the context needed to understand the mechanism you are using entirely.

Dive Deep Into the Relevant Parts of the API

API description is the most technical documentation. Usually, it’s pretty dry and lacks a good overview of the context in which you can use a given method. It shows you all the classes, methods, arguments, and outputs that you have at your disposal.

When available, go through different descriptions of the same or similar things. Often one method is to reference some other—so if you are still lost after reading about the first, then you can check whether the documentation of others makes it any clearer.

Results

With methods, you will either have a change in the internal state of an object or get some output. The API guide should describe both pretty well.

Input variation

Often, methods accept the inputs in many combinations of arguments. The docs will show you all the options to get in all the stuff you need.

Final Thoughts on Documentation

Reading documentation is an important skill and one you can only learn by practicing. Don’t get discouraged as you struggle with your first attempts; it gets better with time.