November 24, 2009 by in Technical Documentation
For those of you who may not know, a style guide is a collection of standards and conventions that is used to facilitate the development of effective technical content or documentation. But you say “We don’t need a style guide – we write software, not books.”
The thing is, even if your organization focuses primarily on creating software applications, there is always a communications aspect to be considered. For example, shouldn’t your software’s user interface and instructions be oriented toward the type of audience that’s expected to use it? Here are a few examples of how style guides can help ensure the success of your software application:
1. Effective Communication with your Audience
You’ve probably noticed that people who work in IT tend to have different ways of speaking about IT than the executives who make decisions about purchasing IT products. And oftentimes, end users have yet another way of speaking about them. Style guides can help ensure that the right language is used for the right reader: executive-oriented marketing materials use execu-speak, installation and customization materials use IT pro-speak, and training materials use end user-speak.
2. Consistency of Language and Formatting
Regardless of the topic, it’s important to be consistent when referring to different components of a software application. Is it a thingamabob or a widget? Is it a button or a window? Is it a screen or a page? It’s not necessarily that one term is wrong and another right (although aptness is an important consideration), but readers can be easily confused by inconsistent references. The same thing goes for consistency in formatting – for example, are you really supposed to type <article_name>, or do the italics and angle brackets signify a variable? Style guides help ensure consistency and remove ambiguity.
3. Ensure Accurate Product References
‘Accurate’ is the key term here – but not just to help eliminate confusion. If your organization creates multiple products, they are likely copyrighted and/or trademarked to protect your intellectual property. If you strive to make accurate product references, you can help prevent challenges to your intellectual property. You might have the best legal representation that money can buy, but wouldn’t it be better to spend money on R&D instead of on litigation about your products’ names? Using style guides can save your organization money in the long run and help you focus on more important things.
4. Clarity for Global Audiences
The explosion of the World Wide Web has created marketing opportunities in places that you might never have even considered before. Some of these places might be populated by people who don’t speak English as their primary language. If so, it’s important that your documentation not include terms and colloquialisms that non-native English speakers wouldn’t understand. For example, there’s that old joke about prompting the user to “press any key when ready,” which caused some extremely literal-minded users to call tech support and say their keyboard didn’t have an “any” key. Also, as machine translation is increasingly used, plenty of English phrases (such as “on the other hand,” “jump on the bandwagon,” “have your cake and eat it too,” etc.) can be problematic. Using style guides can help ensure that documentation and related materials don’t confuse global audiences.
Another reason to strive for consistency – which can be facilitated by using a style guide – is to ensure that your material is indexed properly. Many IT professionals who use technical documentation insist that a comprehensive index be included to help make sense of any new terminology. Because style guides help achieve consistency in technical content, better indexes can be created. And indexing is also an important consideration from the perspective of online search engines, which create the massive indexes that help people find relevant content. If your technical content isn’t consistent, search engines might not be able to index it properly and, more importantly, point the right people to it.
Although the Microsoft Manual of Style for Technical Publications is considered a standard in the industry, at Wadeware our Technical Documentation team can apply other style guides as well or help you develop a unique style guide that’s appropriate for your technical documentation. As mentioned earlier, a style isn’t necessarily about being right or wrong; it’s about consistency and accuracy.