Why Microsoft developers need a style guide

I usually get some flak from readers whenever I suggest that software developers can learn lessons from Microsoft. Not everyone thinks Microsoft is a role model. Nonetheless, I maintain you’d be hard-pressed to find another company outside Redmond that thinks more seriously and deeply about the practices and processes of software development.

Case in point: the new fourth edition of the “Microsoft Manual of Style,” which crossed my desk last week. The “Microsoft Manual of Style” is a style guide for writers. Its goal is to maintain consistency in published writing by settling various niggling points of style and usage. For example, is it “e-mail” or “email”? Do you capitalize “Web”? Is a CD-ROM a “disc” or a “disk”? And so on.

[ Neil McAllister explains why for mobile UIs, it’s developers versus users. | Go deep into HTML5 programming in InfoWorld’s “HTML5 Megaguide Deep Dive” PDF how-to report. | Follow the latest news and insights on programming with InfoWorld’s Developer World newsletter. ]

Lots of publishers maintain internal style guides. Most magazines have one. InfoWorld has one. What makes Microsoft’s style guide interesting, however, is that it applies to all kinds of official communications. Its intended audience includes not just the authors of manuals, articles, and advertising, but the designers and developers who create Microsoft software.

Why do software developers need a style guide? As it turns out, for more reasons than you might think. The manual covers all the typical editorial suggestions, such as using consistent terminology and style, favoring active over passive voice, and avoiding sexist language and excessive jargon. But it also includes a wealth of tips that are unique to the modern discipline of software design.

Elocution lessons for software The gist of much of Microsoft’s advice is that a user’s relationship with computer software is a unique one, and it’s important to craft the language of software UIs accordingly. “We have responsibilities beyond being a producer of great software,” the manual explains. “We think about how our comments will be perceived.”

Much of how users perceive software depends on the tone of the user interface’s language. Microsoft advises designers to maintain a tone that is “polite, supportive, and encouraging,” as well as emphasizes what users can do with the software, rather than what they can’t.

At the same time, developers shouldn’t patronize users. Don’t tell them how easy, fast, or fun your software is; if a procedure is actually complicated, slow, and frustrating, your users will know it. Don’t try to be funny, and don’t assume to know how users are feeling — for example, by telling them not to worry. You should also avoid anthropomorphizing your software with phrases that explain what it “needs” or “knows how to do.”

Perhaps the best advice Microsoft gives, however, is that you should start writing UI text early in the software development process, because awkward UI text can reveal deeper program flaws. Don’t make the mistake of relying on detailed user prompts and help text to solve design problems.

Hidden gotchas of a global audience Given the rapidly expanding global software market, internationalization is one of the most important UI design concerns. For many developers, internationalization simply means translating software prompts into other languages. But as Microsoft’s manual points out, developers should be thinking about international markets even before they reach that point.

For example, UI designers should take pains to write in concise, clear Standard American English. Writing plainly is important for readability, but it also makes the sentences easier to translate. That’s especially true if you’re using machine translation, which can be a huge boon for software internationalization, provided your sentences are unambiguous and don’t rely too heavily on idioms.

What you say to international audiences can be as important as how you say it. Here, Microsoft’s advice isn’t always intuitive. For example, you should avoid mentioning seasons wherever possible to avoid ambiguous associations; remember, Australians celebrate Christmas in the summer. Certain colors have political or religious significance in many cultures, too.

Especially treacherous are those words that have become part of the standard computing jargon but that may carry negative associations for some English speakers. In computer security, for example, a subnetwork containing systems that are exposed to the public Internet is called a DMZ, but that term could have unwanted connotations in war-torn countries with active demilitarized zones.

Similarly, the relationship between USB peripherals could be described as “master/slave,” but these terms could also be considered offensive. (The “Microsoft Manual of Style” says such language is prohibited in “at least one U.S. municipality.”)

Some tips are better than others Occasionally, Microsoft’s recommendations verge on the absurd. For example, you might not think it necessary to admonish developers to “not use slang that may be considered profane or derogatory, such as ‘pimp’ or ‘bitch,'” but apparently it is.

Other sections of the manual seem designed primarily to ensure that writers toe the Microsoft company line. For example, no Microsoft communications may use the term “blue screen” to describe a program crash. Internet Explorer should never be abbreviated. And “hackers,” in Microsoft parlance, are always of the black-hat variety: “Do not use ‘hack’ to refer to improvising a solution to a programming problem. Do not use ‘hacker’ to refer to an amateur programmer.”

This howler stuck out, in particular: “JScript is the Microsoft implementation of the ECMAScript scripting language specification, an open standard. Do not refer to it as ‘JavaScript,’ which is the corresponding implementation by Time Warner.” Huh?

More often than not, however, the “Microsoft Manual of Style” offers sound advice that can be beneficial to any software development organization, large or small. Its advice covers not just user-facing text but also source code comments and SDK and API documentation. And consider this: Independent developers who master Microsoft’s linguistic advice gain one more hedge against competition from offshore outsourcing.

The book’s greatest value, however, is simply that it can get programmers thinking about language in the context of software development. That’s something the industry could use more of. After all, in an information economy, how you communicate information is at least as important as how you process it.

This article, “Why Microsoft developers need a style guide,” originally appeared at InfoWorld.com. Read more of Neil McAllister’s Fatal Exception blog and follow the latest news in programming at InfoWorld.com. For the latest business technology news, follow InfoWorld.com on Twitter.