Is your technical documentation really effective?

Have you ever had to get back to your users and tell them: “this is documented in document xyz”?
If so, do you think your users are mostly not reading the documentation, or reading it lightly?

I think these both would be fair statements, but it would be quite unfair to leave out two points:

  • Does the documentation present topics in a logical, hence effective order?
  • Does the documentation give enough attention to the information that is useful for normal operation or is this information discussed in the very same way as other dull, seldom useful, or way more complex operations?

The other thing to note is that you have an in-dept knowledge of the subject, where your users might not have the whole picture. Your black box probably does not appear that much opaque for you, but how are you exposing users to the information they need?

One way would be to use profiles. Your documentation might be used by different target readers: people with a different understanding and expertise of the subject, or just people with different tasks to perform.
Each class of users with a similar level of expertise (e.g. simple, intermediate, expert) or similar tasks to perform constitutes a profile. Users belonging to the same profile share what I will refer to as need.

Profiles and associated needs, that’s the only 2 terms I need to define in this whole section. It sounds like a good idea to give just a small number of definitions per section, the minimum required for writer and reader to… be on the same page.

Who does identify profiles? Are they the result of a brainstorming session? Possibly. However, who do you involve in brainstorming sessions? Get the right guys on, those who can contribute with facts and not just wishful thinking: this is probably an iterative process so that avoid people with overwhelming ideal-world ideas during the initial sessions.

You should end up with a handful profiles. Well, two scenarios should be possible at this point:

  • If you can define a hierarchy in terms of expertise for such profiles, then your documentation is probably best structured in sections with increasing levels of details and instructions.
  • If there’s no such thing as a hierarchy for the identified profiles, probably each of them should stick to their own section, written specifically for them.

In the first case make sure all users are able to understand where to tap in and make sure they can work their way into the next section if they wish to get more details. Avoid making them feel like things are repeated exactly as in previous sections, apart for a few more command boxes and footnotes.

I can imagine somebody rising their hand and saying: “what if we have a mixture of the two cases?”. As long as you don’t come up with 7 different user manuals that are hard to maintain and keep in sync, you can try and handle that, but keep things simple: the simpler it is for you to write and maintain the documentation, the more you can focus on the effectiveness of the contents.

In any case, entertaining readers while explaining them what’s going on is of fundamental importance. I guess it’s common perception that an entertained brain is more likely to pick up details and side-information, and actually remember about them later on.

Final note: nowadays it is far too simple to cut & paste. Should you need to move paragraphs around to improve readability or ensure to lay them out in a more logical order, go through the whole revised section: fully appreciate what the change has brought in and taken away, willingly and, more importantly, accidentally.

About Luigi Di Fraia

I am a Senior DevOps Engineer so I get to work with the latest technologies and open-source software. However, in my private time I enjoy retro-computing.
This entry was posted in Technical. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s