Category: computing

Bad documentation says what things are. Good documentation says what they do.

The widespread contempt for grammar in society is one of my numerous hobby horses. In school I got the impression that grammar was about diagramming sentences and placing commas. They told us that certain constructs are incorrect, but these were presented as arbitrary societal rules which serve no other purpose than to demonstrate education and get into a good college. Since this was in the 1980’s and conforming to arbitrary societal rules were seen as uncool and silly, grammar was uncool and silly.

What they did not tell us was that not only do words have meaning, but gramatical constructs have meaning too and sometimes if you use the wrong one you will not be understood. This is not always a problem in the situations of daily life since most people know what you meant to say.

But computers are complicated and very flexible. The way software works can be difficult to explain and not entirely obvious. If you are writing the manual but don’t have the grammatical chops to pull it off, your readers can be left guessing. You need to explain how data moves through a system, what steps are taken in what order. You do not need to be a grammar expert, but you need to know how to express ideas clearly, so say the data “enters” something, “is collected” from some places, that it “passes through”. You need to know how to say that one thing was replaced with another without mixing up the old and the new thing.

So pay attention to grammar. Learn to use prepositions to explain where data is and where it is going. Use real verbs. Do not say that “this is the notification e-mail address”. Say “This is the e-mail address to which a warning is automatically sent when the XYZ process stops unexpectedly.” Your users will thank you and they will be more likely to stick around because they understand how your product works and how to use it.