I’ve been checking recently how my students are doing. And what could I do to make it easier for you to do better documentation. I’ve been checking the final work that has been sent to me for review by those of you who have completed a course.

I will collect some of the common mistakes I see, so you can also check for yourself if you do them too.

#1 Writing it Like a Song!

One of the common mistakes I see in the work of the novice technical writers is to forget to make it clear who is your target audience. You are not trying to address their problems!

Novice technical writers tend to write whatever they believe is important in the order they believe is important.

Sorry, folks, it does not work like this!

If you write documentation that looks and feels like a song, you are not targeting anyone with your documentation. Some people will like it, others won’t and will tune in to the next station. Can you guess what it is? Here are some of my favorite choices:

  • Your manager, complaining about you (did you notice it’s almost never about the documentation, but about you?!)
  • The support team, creating a ticket for something you were supposed to have explained already in the documentation
  • Facebook, where to share what a crap the software is (did you notice it’s almost never about the documentation, but about the software being crap?!)

Song writing is not the same as technical writing!

Yes, your documentation might help some people, but you do not know who those people are! You are not targeting them specifically and are producing a generic mambo-jumbo document that do not serve the target audience of your product.

Pros and cons of this approach?

Well, you can say to your boss that you have provided documentation! There is SOMETHING that is delivered.

However, if you write in a generic manner, you will miss the target audience.

In a world that is full of information, if you deliver a generic guide, you are going to have a hard time keeping the attention of the user. What will your customers have to say about it? Well, they will say: “This is not for me!”. And will go and create a support ticket. You will not solve THEIR problem.

What's the solution?

Use your generic guide as a draft. Validate it against the needs of the customer! Then clearly identify the target user of the specific portion of information you are delivering. If your writing infrastructure allows that focus on creating different guides tailored specifically for your user audience.

Still not clear?

Here is an example:

One of my students have to document software for a medical information system. The system has two parts: one for the doctor and another one for the patient.

In the original guide, the student was writing about the system and how to use the modules of the system. The result was that the information for the doctor and for the patient was in the same place!

After taking into account the user role, now we have a user guide that clearly identifies the processes for each target role. And only then it links to underlying information that is relevant for the target user.

In the topics themselves, we also make it clear who is the target by stating it in the text at the beginning of the topic.