(This is part two of an irregular series that I’m doing on writing about software. What documentation does a product need? is part one.)

New technologies often bring along new words and new uses of old ones. Perhaps you’ve made up new names for certain components of the application you’re documenting. More likely, someone else created new names for something that you must document. You also may be introducing acronyms to your reader, and acronyms less common than “HTML” should be spelled out the first time they’re used. Considering how many things “ATM” stands for these days, spelling out an acronym once gives the reader valuable context for its use.

Where can you find a definitive reference for these spellings, acronym expansions, capitalization and other usage rules? These terms usually come from two classes of sources: specifications and software companies. For a freely available spec like the XML Recommendation, there’s no excuse for saying that the acronym stands for “eXtensible Markup Language” or for forgetting the hyphens in “start-tag” and “end-tag”. Just look at the spec. Should the “p” in XPath be capitalized or not? Look at the spec. Is it more proper to refer to “a SQL query” or “an SQL query”? This is a tougher one, because the complete spec is not available for free, but it doesn’t take much detective work to find something authoritative: Wikipedia’s SQL entry includes links to PDFs of a subset of the ISO/ANSI SQL specification. (It turns out that the phrase “an SQL” does come up in the SQL spec, and “a SQL” doesn’t.) So, sometimes a bit of detective work is necessary, but it’s rarely much and always worth it.

Should “internet” be capitalized? Is “filename” one word or two? There are many cases where multiple renditions can be considered proper, but professional-looking documents come from organizations that pick one variation of each such term and stick with their choice. You shouldn’t see “internet” in the middle of one sentence and “Internet” in the middle of another sentence in the same document, in the same documentation set, or, ideally, in two different documents coming from the same company.

To implement this consistency, those in the publishing business (and remember, a software company that wants their documentation to be taken seriously is in the publishing business) have what they call style guides, which document their use of words that may offer a choice of usage. (A former co-worker who had worked at Penthouse Magazine—note that I’ve resisted the temptation to turn that phrase into a link—once told me of a screaming fight in an editorial meeting over whether “butt cheeks” is one word or two. I guess every profession has its professionalism.) You can buy the New York Times Manual of Style and Usage at Amazon or any large bookstore, but even better for people documenting software, large software companies often publish their own style guides and sometimes make them available for free.

Sun publishes Read Me First! A Style Guide for the Computer Industry and Microsoft offers the Microsoft Manual of Style for Technical Publications. (The latter was once available for free on their website, but my link to it no longer works, and searches don’t turn anything up.) The Apple Publications Style Guide (PDF) is a available for free download, and Oracle’s Browser Look and Feel Guidelines is available online.

Some, like the Oracle one, concern application development more than documentation development, but they still provide the prose writer with a good reference for terminology. The Microsoft and Apple guides are particularly important when writing about GUI applications running on those platforms. When you tell a reader how to fill out a particular dialog box that pops up on a screen (and remember, a dialog is a conversation between two or more people—a pop-up window with a form to fill out is a dialog box, not a dialog) you need a solid handle on the correct vocabulary for describing the potential parts of a dialog box. “Combo box” is a proper technical Microsoft term, and combo boxes are different from list boxes, and you should look up the difference if you have to refer to either in documentation.

Don’t underestimate the value of creating your own house style, especially if there is a team of more than one writer working together on documentation. When you do choose between “Internet” and “internet” or “filename” and “file name”, document it and make sure that everyone who does any writing knows where to find the list and what to do if they have something to discuss and add to the list. Terms related to your own software are especially important to cover on this list.

Call me picky if you like, but consistency (both internally and with authoritative material outside of your control) is a mark of professionalism, and if you’re charging money for your product, you want it to look professional.

2 Comments

By Dan Brickley on March 8, 2006 2:17 PM

Kinda relatyed — there are some glossaries on the W3C site, http://www.w3.org/2003/glossary/ with details here: http://www.w3.org/QA/2003/01/Glossary

I couldn’t find the RDF, but it’s around there somewhere…

By Bob on March 8, 2006 4:04 PM

Thanks Dan. Considering how many of those words have different meanings in different contexts (even when limited to the domain of information systems), these glossaries are very valuable supplements to the W3C specs themselves.