10 documentation mistakes

The best way for a technical writer to find mistakes is have his documentation checked.   I once gave a software manual to the girl at the reception, It was an eye-opener. Obvious steps were missing and she could not complete some of the procedures. Just recently I got stuck myself trying to troubleshoot some drive problem on my computer. The documentation first bluntly stated that I could double click it a few times to bring it back to life again. It forget to tell that some credentials were needed to do so. The option of disconnecting the drive was not even mentioned!

Some mistakes from my own experience and that of some of my colleagues:


No testing needed

Every piece of documentation has flaws, contains errors or is a at some points not precise or elaborate enough. Get some testing process in place and hope management will go along. Stay clear of hypes like Agile working were there is no proper place for documentation let alone testing it.

Underestimating the look and feel

One of my colleagues once came up to me asking to pimp his document. “So they don’t look at all the mistakes that might be in there,” was his reasoning. Is that look and feel over content?! No, it is taking your audience seriously. By putting some effort into stylisation and such you communciate valueing your audience.

No pictures

Was it a Microsoft style suggestion that in a procedure after seven steps at most you should put a picture. A former colleague of mine was amazed that i questioned his endless procedure of more than 20 steps without any picture included. The reader gets lost, forgets where he is in the procedure while looking for an anchor to hold on to. Just try to make sense of the vdeo recording instructions below.VideoRecorderInstructions.jpg

Too much markup

Nobody reads the document convention when they are looking for an answer to their problem. There can be a brilliant idea behind markup differences as is the case in the company i’m working for at the moment. But their are readers who will look for [File], including the brackets, or get lost when you tell them to push <Ctrl> – <A>. Markup is superfluous when it does not serve a clearly identified purpose.

Download something

You browse to a website looking for an answer. There is a pdf. You must download it, and then you can start your search. This is not the way to go. Instead of a pdf an online help would have suited you better.

Passive headings

Try to use active headings. In a machine manual “Wheels” is questionable while “Repair a wheel” directs the user straight from the TOC to a solution.

Lack of searchability

In longer documents (100 p +) an index is a handy add-on to the searchability of your document. Write headings in such a way that they represent a search term. And, finally, an art i am still trying to master, write with search terms in the back of your mind. This means duplicating search terms throughout your document.

For API-documentation this is a key issue. Some API documentation is rather voluminous. Dont invest in lengthy drill down menues in a left or right pane , but write long pages so developers can use Ctrl-F to find what they are looking for.

Screenshots are not the Holy Grail

Screenshots are great but don’t overdo it. Filling a screenshot with text describing which is what does not answer any questions. It is pleasant for the eye and it will definitely score you points in the ‘look and feel’ area, but a customer will go through your manual looking for this screenshot. He has a problem. That problem cries out for a solution. Overview screenshots don’t help in that respect.

Outdated documentation

It happened to me, it could happen to anyone; sending out documentation that is outdated the moment you send it. There’s only one cure for this: be known, be liked, be disliked, go to meetings, give documentation the place it needs, get your information, organise processes, make friends, push forward, succeed. Well, a bit too many steps for one cure…

Forgetting about your audience

By far the biggest mistake. Who are you writing for, what are their needs, what is their knowledge level. Should your grandma be able to understand it, write for your grandma. Should a developer work with it, get a few of those whizz-kids onboard for testing. Is it a machine manual, let engineers test it. Is it API-documentation, let these JSON, PHP and Curl guys and girls feed you with information and examples.







Geef een reactie

Vul je gegevens in of klik op een icoon om in te loggen.

WordPress.com logo

Je reageert onder je WordPress.com account. Log uit /  Bijwerken )

Google photo

Je reageert onder je Google account. Log uit /  Bijwerken )


Je reageert onder je Twitter account. Log uit /  Bijwerken )

Facebook foto

Je reageert onder je Facebook account. Log uit /  Bijwerken )

Verbinden met %s

Blog op WordPress.com.

Omhoog ↑

%d bloggers liken dit: