Journalistic Over-enthusiasm

Sometimes you just have to feel sorry for developers. They slave away with their high-powered computers, multiple monitors, and earphones stuffed into their ears; glued to the same chair day after day as they battle with endless lines that basically all say the same thing. With only a hundred or so different keywords they can use, they are forced to try adding some variety to the content by dreaming up exciting names for variables, varying the number of spaces between words, and maybe (in a fit of carefree adventurousness) putting those curly bracket things on the same line as a word!

Just think, if they had the freedom a documentation writer, how interesting their job would be. They could vary the words a bit whenever it got boring, or even use different ones. I mean - as a documentation engineer - you have literally (and literary) almost a million words to choose from (see if you think I'm exaggerating), and you can change these in all kinds of exciting ways. You can vary the tense of words in the text, add different word endings, or just add some extra superfluous ones when the paragraph looks a bit sparse. Best of all, you can invent your own new words in some cases, especially when describing some new product or feature. I managed to get away with "Weblication" in a book many years ago, though a Web search now seems to turn up lots of references to this that aren't mine. And in non-formal writing, you can even use punctuation to make things more interesting in an add-plenty-of-hyphens kind of way, or by appending several exclamation marks!!!

Unfortunately, for developers, code compilers tend to complain when faced with keywords like "print-whatever-you-think-is-best", or "do-something-else-for-the-time-being", and using exclamation marks generally has little impact on operatability (there you go, another new word). Calling a method as "GetCustomerDetailsReallyQuickly!!!" is unlikely to increase application performance; and "whatever" is not really useful as a keyword - even within an "if...else" clause.

It's not even as though developers really can use exciting variable names. Of course, C++ programmers are incapable of inventing variable names anyway, having been conditioned as part of the learning process to just change the initial letter of the class name to lower-case. However, C# and Visual Basic developers are allowed to be more inventive, though variable names such as "notSureWhatThisIsYet", "ifThisIsNullWeveGotAProblem", and "myReallyUsefulStringForUseAllOverThePlace" tend to be frowned on by managers. But at least they can usually get away with leaving rude words in comments that the test team won’t see.

What about made-up stuff? Not something you'd usually associate with documentation engineering, but a recent request I received was for twenty totally fictional news articles about five companies that don't actually exist. The articles were for a forthcoming sample application, so I guess it makes sense, and I did have some fun writing them. Rather like an article I wrote some years ago for a sample sports car Web site that described how they can now breed cows in different colors to get the right shade of leather for the seats. Only this time it was about companies that build railway carriages and office blocks, companies that sell private islands and edible grocery store paper sacks, and companies that make pasta burgers.

Just imagine what would happen if you asked a developer to build twenty fictional applications. I suppose they could just take the week off and then explain that - as they are fictional - you can’t actually run the programs they spent all week creating. More likely, you'd get applications with windows full of incomprehensible and unrecognizable symbols and controls that - being fictional - don't react to even the most frantically clicked mouse or thumped keyboard. Err ... hang on a minute; I reckon I've already used all of those applications...

So, for the documentation engineer, life should be a breeze - a constant stream of exciting new opportunities for inventing words, exercising syntax, punishing punctuation, and stretching the bounds of dictionarial exploitation. Unfortunately, there is bad news. In the days when I used to write books for independent publishers, they forced us to abide by something called the "Chicago Manual of Stuff". As I never read this, I used to depend on the editor to convert my beautifully crafted text into something that sounded like it came out of a sat-nav. Usually I could re-contort it so it was a bit less artificial in the rewrite without anybody noticing, but it was a constant battle.

And now? Faced with producing official Microsoft documentation I've had to concede, and try to dampen my journalistic over-enthusiasm. Now I have not only an electronic "manual of style" that contains what seems to be several thousand pages, but an editor who actually knows it all off by heart! Still, the text usually comes back with a remarkable resemblance to what I originally wrote. Either I'm finally getting the knack of this, or Tina is exceptionally gentle with me...

Skip to main content