Articles>Style Guides

What’s More Important, Content or Process?

While style guidelines can be useful for maintaining consistency across a set (or several sets) of documentation, the editors that I worked with viewed the style guidelines as sacrosanct. Any deviation, no matter how small, was punishable by a nasty email and a sharply worded note to the offending writer’s manager.

Sometimes, You've Got to Break the Rules

Sometimes, you don’t need documentation made up of perfectly-chosen words and phrases. Instead, you need something that can be easily scanned, easily understood, and easily digested. Documentation that distills the main points quickly.

Writing Great Documentation: Technical Style

Now that I’ve discussed what kinds of technical documentation to write, I can move on to the question of how to actually develop a writing style that produces great technical documentation. So how do you learn to write (anything) well? There’s only one answer: you’ll learn to write well if you write. A lot.

Choosing the Right Style Guide

Style guides can improve the quality and presentation of documentation. They establish a layer of professionalism that may not have been there before. They also reduce arguments and ‘loose cannons’ within the department, as the style guide becomes the acknowledged reference. There are at least four points to consider when selecting a style guide.

Controlled Language – Does My Company Need It?

Controlled languages use basis writing rules to simplify sentence structure. Here is how they work and how your company can benefit from introducing a controlled language.

Style Manuals: The Politics of Selection

Bette Frick and Betsy Frick discuss how a style manual can save time and money, how to select the proper style manual and get buy-in, and how to create a style guide to use in conjunction with a style manual.

Consistency and Community-Generated Content

I’ve been collecting examples of wildly inconsistent writing lately. I’m not sure why these have stuck out to me, but when I think of book sprints and community writing events, consistency is an important, though sometimes difficult, goal and outcome.

Style Rules for Job Position Names and Titles in Policies & Procedures

Have you struggled with job position names and titles in your policies and procedures (P&P) content? Here are several style rules to follow.

Do I Really Need a Style Guide?

Style guides recommend certain styles. In the domain of technical communication, we refer to guides for writing style, presentation of content in user documentation and technical documents, and graphical user interface of software and web sites.

The Missing Manual Authors’ Guide

This Authors’ Guide tells you everything you need to know to write Missing Manual. It starts out by giving you a brief introduction to the Missing Manual way of explaining things and then takes you through the nitty gritty of style guidelines, figure formatting, and so on.

The Global English Style Guide

A review of "The Global English Style Guide: Writing Clear, Translatable Documentation for a Global Market" by John R. Kohl.

Do I Really Need a Style Guide?

So, after all, I must follow those infernal style guides. I am straight-jacketed. Am I not?

A Web Policy is a Policy, Not a Standard

I've noticed recently that people (and organizations) often interchange the policies and standards labels as if there is no difference between them... like those who insist the Web and the Internet are the same. I'm not one for splitting hairs, but in this case, policies are truly not the same as standards and it's important to be clear about the distinction.

Fifty Years of Stupid Grammar Advice

April 16 is the 50th anniversary of the publication of a little book that is loved and admired throughout American academe. Celebrations, readings, and toasts are being held, and a commemorative edition has been released. I won't be celebrating. The Elements of Style does not deserve the enormous esteem in which it is held by American college graduates. Its advice ranges from limp platitudes to inconsistent nonsense. Its enormous influence has not improved American students' grasp of English grammar; it has significantly degraded it.

How to Use the Bulleted Lists Properly in Your Technical Document?

Bulleted lists are important in technical writing. They summarize information in a manner that is easy to read and absorb. Use them whenever you can to get your information across quickly. Bullets are ideal for things-to-do, equipment, sets, collections, cooking ingredients, and all kinds of other lists.

The Global English Style Guide: A Review

Many good style guides exist. Why do technical writers need another style guide? Unlike other style guides, this book covers grammatical structures, not only particular terms. The book has more than 200 pages of text (plus 4 appendices) that give detailed explanations of both good practice and bad practice.

One Space Or Two Spaces?

When I began writing technical documentation and courseware for Guru Labs, I asked a question during training about whether we should be putting two spaces after a period, colon, question mark and exclamation point, or one. The answer shocked me, as I was hoping for the standard answer as a means of teaching the rest of my colleagues. The answer was ONE space, not two. Then, I listened to the argument.

Style Guides? Dictionaries? Who Cares?

You should! Whether you're a corporate or a freelance communicator, a style guide and a dictionary are among your most important tools. And all the departments in your company or your client's company should be using the same ones, designated by their communication departments.

404 File Not Found: Citing Unstable Web Sources

Researchers, including students, must accommodate to the mutating character of hyperlinks on the World Wide Web. A small study of citations in three volumes of BCQ demonstrates the phenomenon of 'URL rot,' the disappearance of sites cited in the sample articles. Digital technology itself is now being used to create pockets of permanence, but with the understanding that preservation of content is only one ingredient in the mix of media and format migration. Databases like JSTOR offer digitally preserved copies of many scholarly journals. Online journals and search engines may offer their own archives. In general, researchers should cite digital articles in databases where possible and consider avoiding references to online journals with print editions.

Editing the Baldridge Quality Award Application

Editing the Baldrige award application requires unique plans for the writing, editing, reviewing, and publishing cycle. The editor’s role includes training nonwriters to write, establishing style guidelines, setting reasonable schedules, and editing each draft.

Designing Automated Custom Templates as Part of A Global Corporation's Style Guide

When CH2M HILL staff ignored the Times 12 standard for document production and began inventing their own formats, they often bypassed the company's Publications groups, resulting in client bewilderment and anger. We will orient the audience to how creative thinking and innovative programming made it easy for staff to produce consistently attractive and effectively formatted documents. We also will demonstrate the final Toolset version and supply information about how you can apply the benefits of a Toolset product in your company's environment.

Developing a Corporate Style Guide

Developing corporate style guides helps documentation departments or any other group apply the same standards when writing documents for publication or presentation. Three types of style guides exist: static, dynamic, and multi-level. The information that goes into a style guide depends upon corporate and department guidelines. Publishing, promoting, and maintaining style guides are the responsibility of the responsible department. In many corporations this may be the technical documentation department, while for others it may be the corporate marketing or internal communications departments.

Communicating Style Rules to Editors of International Standards: An Analysis of ISO TC 184/SC4 Style Documents

Committees within international standards organizations write standards. Prior to approval, these standards must pass through several reviews for technical accuracy and stylistic appropriateness. The style considerations are based on documents published by both the umbrella organization (International Organization for Standarization, or ISO) and the various committees and subcommittees within it. Because authors and editors who use these documents frequently do not have English as a first language, the documents must explain unambiguously just how committees should prepare their documents. This study looks at a sample of those instructional documents using Restricted and Elaborated Code and metadiscourse analysis to determine how easily users can read and understand the material. The findings suggest that the documents do not send a clear message to authors and editors and can be stylistically hard to understand. Consequently, the approved standards themselves are hard to read and interpret.

The Blue Book of Grammar and Punctuation

If you are still struggling to decode the complex jargon and structure of English grammar with a long list of reference books, relax. The long wait for a reader-friendly book on English grammar is over. With her straightforward and perfectly-logical approach, Jane Straus reveals the mysteries of grammar and punctuations in her book The Blue Book of Grammar and Punctuation. The book is extremely well-organized, allowing readers to quickly locate the required topics. Concepts are described in clear and simple phrases, backed with examples from everyday language usage.

Intelligent Terminology Management

Using multiple terms to refer to the same concepts can be a major cause of confusion. Ray explains how to implement a process to consolidate the terminology used by your organization.

Style Guides

Style guides are used to provide a consistent look and feel. They should be defined as part of usability requirements and conformance should be monitored during development.

Social Rules for Creating a Style Guide

Creating a style guide may initially seem like a terminology affair ('option button' or 'radio button' - pick one), but the real challenge lies in persuading the department to adopt new style principles. Some writers will feel threatened by change, and respond in bizarre and unpredictable ways. Whisper campaigns and ambushes may lie in wait for you. Beware, innovative editor! Before you even think about the literary details of style, prepare to do battle with the true Goliaths and Grendyls: the department itself. By following these five rules below, you can avoid an unexpected apocalypse when you reveal the new guide.

Keep Spelling Consistent With a Style Sheet

Consistent spelling and punctuation increases your website's credibility. Often it's your decision: 'inhouse' or 'in-house', for instance? Either one is correct, but you must use the same punctuation throughout.

Standards for Online Content Authors

The standards on this page include non-technical standards relevant to all web authors and technical standards relevant to some web authors.

Microsoft Manual of Style for Technical Publications

Microsoft is one of the largest software companies in the world. Thus, with their rich experience in documentation it is only natural that they share it with the rest of the IT industry. The Microsoft Manual of Style for Technical Publications, Third Edition (MSTP) is the latest step in this direction and takes care of latest technologies and technical terms.

Fear of Punctuation

So maybe you do know how to add memory to your computer or program your cell phone, but do you know where to put a comma in a sentence? If you have a sentence followed by a list, do you use a semicolon or a colon? Does the period go inside or outside of quotation marks? How do you keep up with changing rules of grammar and punctuation when you can't remember where to put the apostrophe? People often fear punctuation because the rules have changed and they continue to do so.

Five FAQs About Business Writing

A few style guide tips for novice business writers.

Creating, Implementing, and Maintaining Corporate Style Guides in an Age of Technology

This article details a step-by-step process for creating, implementing, and maintaining a corporate style guide to ensure consistency in organizational communication. Through literature research, analysis of sample style guides, and practitioner interviews, this article provides recommendations for gaining management support, building a process to develop a style guide, determining content, encouraging employee buy-in, and maintaining a corporate style guide.

Not a Style Guide: Creating a Quick Reference Grammar Guide for Writers

When approached by a group of curriculum design specialists to develop a job aid that would help analysts and trainers solve some of their most common writing problems, the Multinational Customer and Service Education (MC&SE) editing group from Xerox Corporation went to work to produce The Write Stuff: When to Use a Comma and Other Writing Rules. This paper focuses on the Leadership Through Quality process the editors used to develop this reference tool. It also describes how The Write Stuff addresses some of the most common writing problems editors encounter in the course of a working day.

Collecting Books about Editing

Intercom's 'friendly editor' discusses his extensive collection of dictionaries, grammars, and other books of interest.

Polished Panache: The Empowered Corporate Style Guide

A customized style guide is a document that defines the specific formatting, mechanical, punctuation, and spelling standards for your department or company. When you decide that you need a customized style guide, many questions arise: Where do you start? How do you get there? Exactly where is it you want to go? Are there more issues you need to define? Deciding that you need a customized style guide is the first hurdle. Persuading upper-level management to fund the guide is the second hurdle. And then it’s off to the races...

Using a Doc Spec for Printed Books

All technical documentation projects benefit from a good content plan or 'doc spec.' The doc spec is a blueprint for a document. It identifies the product, users, source materials, and subject matter experts (SMEs). It also provides a preliminary outline of topics and estimates the work effort to produce the document. The doc spec template is simply a tool that guides you through the document planning and estimating process. Your customized doc spec serves as a record of the who, what, when, why, and how of your project.

Using a WWW Development Design Document to Create a Comprehensive Web Site

Technical Communicators are eminently qualified for Web publishing as it is a natural extension of our writing abilities. However, we must be careful to avoid the pitfalls of Web publishing and contribute to the host of glamorous Web sites that lack content, are difficult to navigate, and do not satisfy the ultimate goals of the organization or institution the site represents. One proven technique for planning and implementing a Web site is the creation of a WWW Development Design Document. By championing the development of this document, communicators return to their knowledge roots of organization and writing.

Reconsidering Some Prescriptive Rules of Grammar and Composition

Technical writers and editors are beset with rules. As authoritative as they are, published style guides such as The Chicago manual of style, MLA, APA, and Gregg do not address reading theory but hang their prescriptions on the flimsy mantle of tradition. This article challenges some putative rules of grammar and mechanics in an effort to improve technical texts for the people who read them.

Handling Internet Addresses in Text

How to present complete and intelligible Internet addresses and where to break long strings of letters, digits, punctuation, and symbols on the page.

The Curse of Yocto

Several years ago, four new prefixes, for representing very large and very small measurements, were introduced into the International System of Units (Système International d'Unités, or SI): yotta, zetta, zepto and yocto.

Hand-Picked Descriptive Words

Writing a good description is fun, but it's delicate work. We recognize vivid writing when we come across it, and we know the bad stuff, too -- it makes us squirm instinctively. Here are some types of descriptions the world can do without.

Necessary Transition

As writers and editors, we understand instinctively that readers need transitions, but we also work at getting rid of unnecessary words.

Verbs with -ize: Efficient or to Be ... Ostracized?

A discussion of whether neologisms such as 'prioritize' have 'arrived' yet.

Localization Guidelines for Your User Interface

When delivering your product in foreign languages, it is important to consider how the user interface will appear to users around the world. While there are no hard-fast rules, the following suggestions provide some guidance in facilitating localization in regard to your user interface.

Do-It-Yourself Style Guides for All Occasions

A style guide is a formal set of editorial decisions for a specific set of documents. It can serve many functions, and can apply to many kinds of 'documents'. Whenever you have a number of similar documents to create or edit, a style guide can save time and energy (thus reducing costs), and improve the final product. The contents and structure of your guide can be form-fitted to meet your needs. If you start small and follow these suggestions, you can easily generate a style guide that will be welcomed and used.

Using Manual Quality Tables To Improve Manual Quality

Technical writers need to decide what information is to go into a manual, and in how much detail. Such decisions can have a crucial effect on manual quality. Poor decisions can result in published manuals that lack required information, contain unsuitable or unnecessary information, or repeat information in other manuals. To help make better decisions, Hitachi technical writers use Manual Quality Tables. The tables specify what type of information is to go into a manual, the required level of detail, and sources for the information. These tables enable writers to itemize the required contents of a manual before starting to write the manual. In addition, during later revisions, the tables enable writers or reviewers to easily discover any topics that were left out in the original version.

Capitalization of Headings and Titles

The following summarizes the replies to the question of 'capitalization of headings and titles' in the mailing list tcf-gen in recent months.

Do Technical Writers Need an International Standard for English-Language Spelling?

He demonstrates how ministers of state who speak different languages often choose English as the most convenient language of communication. He cites the 11-nation European Central Bank in Frankfurt as a typical organization that works only in English. And he notes that many of the journals published by respected international organizations such as the Pasteur Institute also are published in English. TC-Forum is another example.

The Current Demand for Style Guides

During my research for a book project, I have found style guides in a wide variety of forms. Some are only a couple of pages. Others consist of hundreds of pages, delivered in ring binders. Some companies produce well-printed and bound books (for example, Microsoft and Sun). A lot of style guides, differing in quality and size, are in the Internet. Most of them cover the design of web pages; only a few deal with document design in general. From one company I received a multimedia CD containing their style guide. It is a well-designed piece of software, presenting graphic arts, sound and video.

Do Not Forget Bibliographical Data in Technical Documentation!

Information products, e.g. manuals, drawings etc, must, besides the technical message, contain certain formal data, which too often is left out. Proper formal data contributes to good order and favours the producer as well as the user of information products.

An Exchange of Views

A discussion about INTECOM's project for researching and establishing English-language documentation guidelines.

Spelling in TC-Forum

There are several ways of spelling English – the English/Canadian style, and the American style. Both are correct.

The Use of Capitals

The question to the list-subscribers was I am looking for studies dealing with the difference between small letters and capitals. Are small letters easier to read? In France, road signs are written in capitals but it is not the case in the US or Canada.

Developing a Company Style Guide

Every company that produces external publications--whether brochures, research papers, or reference manuals-benefit from a company style guide. This paper discusses the advantages of a style guide, why a company-specific style guide is preferred, how to develop a style guide, and what a style guide should (and should not) include.

Fear of Dusty Tomes

Many grammar reference works take what is a relatively simple subject and, with unnecessary expansion and elaboration, turn it into an impenetrably dull experience for the reader. In this article, I'll take a brief look at three books that offer an easy and readable alternative.

Writing Processes

Our Writing Guides help you locate information quickly on specific topics. These guides focus on a range of composing processes as well as issues related to the situations in which writers find themselves.

Terminology and Spelling for Web-Related Concepts

Generally speaking, 'Web' as a short form of 'World Wide Web' is capitalized, with one exception (webmaster). However, your company style may prefer the lower-case version.

Use of Hyphens

This page collects a series of notes from readers of my newsletter, and my responses to those notes, arising from an article in issue 60, 13 May 2002. I thank those who took the time to write and explain why some hyphen usage is considered to be correct or incorrect.

You Send Me: Getting It Right When You Write Online

This book addresses the issues of online writing and particularly writing e-mail, which should concern all us who spend a good chunk of our days in front of a computer screen creating and replying to e-mail messages. The book is structured in three parts: 'The virtual mensch,' 'Alpha mail,' and 'Words of passage.'

Style Sheets and Grammar

A collection of online resources about style guides and reference sites about grammar.

Building a Better Style Guide

Why are style guides so frequently created, but so rarely successful? All too often, businesses ask for a style guide as a means to create a common look and feel, in the belief that it will solve usability problems and establish consistency between applications – only to be disappointed in the results. Even if such a style guide is followed carefully, the resulting interfaces may not meet usability goals.. This paper explores strategies for creating a style guide that is more than a simplistic rules book. By making the style guide part of the process, it can be used to promote a shared vision, to help the product meet business and usability requirements for consistency and…it may actually be used.

Choosing the Right Style Manual(s)

Editors should consider at least four points in selecting, or reevaluating, primary and secondary manuals.

Look at Common Style Differences in Choosing Manuals

Style manuals often differ on important points, and one way to choose a manual is to compare them on some of those points.

Painless Ways to Improve Colleagues' Grammar

Instead of confronting individuals, raise all staff members' awareness. Use humor to help people recognize errors and remember correct usage.

Style Guides and Technical Writing

A style guide consists of formats used when creating documentation. Some companies maintain a formal style guide and adhere to strict documentation standards. Other companies may be more informal, but still maintain some semblance of a style guide, even if it is only an example of the documentation they create.

Appearing for Sentence

Commas, semi-colons and colons are the sentence tidiers. Used correctly, they'll give your written language the 'punctuation' that pauses, voice modulations and gestures provide when you speak.

Are We Agreed?

'Agreement' refers to elements in a sentence having the same number, gender, case or person. In English, it's probably an issue only for number (that is, singular vs plural) and case (that is, 'I' vs 'me', 'he' vs 'him' and so on).

Capital Punishment

Many documents suffer from over-capitalisation. The writer sprinkles capitals everywhere in an attempt to make words stand out - with the result that nothing stands out. Here are some simple rules to help you avoid this capital offence.

Caught in the Active

Have you been told, perhaps by your computerised grammar checker, that too many of your sentences are passive? Have you heard the rule of thumb that at least 80 percent of the sentences in any passage should be active? If you've had the problem or heard the rule, and wonder what the terms active and passive mean, and why one is good and the other frowned on, this article is for you.

The Elusive Apostrophe

Like teenagers and salespeople, apostrophes are frequently there when they're not wanted, and not to be seen when they're needed.

Gender-Neutral Language

One of the most significant changes taking place in English is the rejection of the way that 'man' was assumed to include 'woman'. Most of us want our writing to be friendly and inclusive. How can we avoid using 'man', 'he', and 'his'?

Making Sense

When we are trying to communicate complicated ideas, it is important to be specific. One way to ensure that you will not be misunderstood is to look at your use of 'scope'. 'Scope' refers to which words go with which to form a 'sense unit' in a sentence; for example, which nouns are covered by a particular verb or preposition. Often, poor punctuation or poor sentence construction messes the scope up. Scope isn't easy to explain, but you can get a handle on it once you have seen a few examples of how it works.

Muddled Sentences

Misplaced modifiers are usually obvious and easily fixed.

Reported Speech: a Tense Issue

The tense of the verb in a statement is, as a general rule, shifted back in time in reported speech.

Sentenced to a Cruel End

A simple definition of a sentence is: a set of words that expresses a complete thought and contains a subject and a predicate. Let's look at this.

Using 'Which' and 'That'

'That' clauses form a sense unit with the word they're attached to, and that's why they aren't preceded by a comma.

Nonstandard Quotes: Superimpositions and Cultural Maps

We regularly chastise students for placing quotation marks around words that are not direct quotations. Yet, as this research shows, professionals use nonstandard quotations routinely and to rhetorical advantage. After analyzing the various purposes nonstandard quotations serve, I argue student use of the marks jars us not because it departs from good practice but because, through them, students invoke voices we do not want to recognize.

Stylesheet or Stylesite? A Case Study

CNET’s Stylesite for the Technology Department’s Documentation and Training group provides an online resource for writers and trainers. The continuing development of this tool encompasses site development, content creation, and a fluid process of drafting standards. The site observes many of the same rules 'imposed' upon the writers, and offers them a rare opportunity to collaborate with their editor in the production of a manual of style.

Developing and Implementing Project Style Guides

Style guides can be very effective tools for achieving uniformity in documentation. Their use can enhance the appearance, readability, and tone of a document. In this progression session, I would like to discuss why style guides are needed, what should be included in them, and how to create a style guide appropriate for your project. I invite participants to bring style guides with them for critique and discussion.

Communicating in Spite of TLAs (Three-Letter Acronyms)

The unchecked use of acronyms and initialisms in technical writing presents a huge obstacle to clarity and readability. Although technical communicators are certainly more aware of this problem than are the engineers, scientists, and managers with whom they work, they need concrete guidelines and at least a small degree of self-righteousness on this subject to help them cope with the onslaught. That acronyms frustrate communication is well-founded in linguistic theory and common sense. Suggestions for mitigating their effect include issues of audience, term selectivity, frequency and occasion of use, and aesthetics.

Getting Your Style Guide Written!

This paper describes how to approach the project of writing a stand-alone Style Guide that provides technical writers and other employees with a reference for documentation procedures and policies. A Style Guide project is often placed aside while other priority projects forge ahead. This occurs for several reasons, the most common being that writing a Style Guide is a monumental task! This paper provides you with the skeleton to manage a Style Guide writing project and deliver the product on time

Loose Ends: Standards and Styles

Several readers have sent me e-mail comments and questions recently that might be of interest to others. (Even Eye readers who don't spend much time on the Web tell us they're interested in picking up this kind of information.)

Usage Experts Change Their Minds, Too

Many terms and constructions frowned on a generation ago have been admitted, like many new words, into mainstream parlance and have gained wider acceptance than before. An example is tycoon, in the sense of a wealthy businessman, labeled 'informal' in the first edition of AHD but accepted in the third. Another example is balding, called 'entirely vulgar' in a usage note by panelist Katherine Anne Porter in the first edition but entered without stigma in the third.

The Reference Book That Editorial Eye Built

About three years ago we were asked whether we would be interested in writing a new and different kind of style manual: * In addition to covering all the traditional style topics, such as capitalization and punctuation, it would have chapters on grammar, confusable words, usage (including bias-free language), and all aspects of production, from design and typography to desktop publishing and printing. * Its audience would be the vast majority of working writers and editors, not just those who work with scholarly manuscripts. * It would be written and organized in a friendly, easy-to-read style and reflect the impact of the computer on every aspect of the publishing process. Although we were a bit cowed at the thought of tackling such a big project -- it turned out to be 836 pages -- we didn't see how we could turn down the chance to create a guide that was truly useful.

Shifty Adverbs

Decide where to place the adverb in parentheses in these sentences to best advantage -- for the sound of it and for best sense. That is, place it near the word in the sentence you wish to emphasize. One sentence doesn't involve a decision about placement next to the verb at all.

The Struggle for Gender-Free Language: Is It Over Yet?

All current style manuals address in one form or another the need for bias-free, inclusive language. Most writers and editors deal with this issue regularly — we've installed mental alarm systems that go off when we sense bias or something that can be construed as bias. In fact, some commentators say we've gone too far toward what social commentator Christopher Cerf calls, with grave facetiousness, 'content-free writing,' lest language offend anyone, anywhere. Does gender-free writing still present problems, and if so, how are most of us resolving them? After all these years of practice at being evenhanded, consider several litmus tests.

When Technical Writers Don't Write Technically

Technical writers are often asked to write more than just end-user manuals or online help systems. Due to company size, layoffs, or a lack of resources, the technical writer might also be expected to deliver marketing communication collateral, Web site content, training materials, and more. These additional tasks can daunt those who have not been formally trained in other writing styles or those who do not switch writing styles easily.

The Most Obvious Fault in Technical Writing

The most obvious fault is wordiness. Fortunately, long-windedness is something that editors are particularly well equipped to fix. Take a look at our manuals. They are huge, and their very bulk can make them inaccessible, especially when they are not equipped with a good index or adequate indicia in the corners of each page.

The Style Guide is 'Dead': Long Live the Dynamic Style Guide!

Nobody, least of all an editor like me, would argue that printed style guides are really dead--at least not in the sense that they're no longer with us and no longer useful. Yet there's no doubt that printed style guides are looking a little antequated these days. Despite how useful the guides are to writers and editors, they're simply too static for most writers, and don't take advantage of computer technology to make the writer's working life easier. But if you're thinking that online style guides are inherently better solutions, think again; using the computer to find static information certainly helps, but simply moving a paper guide online only exchanges one form of 'static' for another.

A Global Style Guide: Working Together Around the World

As a result of acquisitions and mergers, companies can find themselves working together worldwide and sharing documentation to distribute in different markets. The original source documentation will probably need to be adapted by some of the companies in the distribution channel to accommodate different languages, branding and content in order to meet the requirements of these different markets. This sharing and reuse of documentation between companies worldwide is easier when all the companies in the distribution channel share a common style guide.

Writing Consistently Across Media: Ten Proofreading Tips

Last time I wrote about consistency in online writing. Soon after, I received an email from Leslie Drechsler, a reader in Tustin, CA: 'As a Marketing Communications Specialist, I'd love to hear your ideas on how to successfully implement consistency in an established business,' she wrote. 'I thought developing a company style guide would solve the problem. But perhaps there are other ways to approach it. 'Perhaps this could be the subject of another article.' Here's that article, Leslie.

Frequently Asked Questions About English

Asterisks.com answers some frequently asked questions about English usage.

Style Sheets: The Abbreviated Answer

As a project moves from writer to editor to designer and ack again, style sheets (abbreviated versions of style gides) offer quick access to answers during documentation development. Style sheets provide consistency, give a quick-reference point, set a project’s style from the beginning, eliminate confusion on major style points, and serve as a double check during revision. Designed specifically for a project, style sheet formats include laminated sheets and standees, and content ranges from grammar references to contact information.

A Matter of Style: On Writing and Technique

Many editors and writers will find A Matter of Style useful, but as readers, most will find it frustrating. Matthew Clark, a professor of classical literature and a musician, addresses the book to editors and writers, both creative and non-fiction, and especially to academic writers. The book is not an introduction and Clark assumes that his readers “already have a good grounding in the basics of grammar and style” (p. iv). He skips quickly through a chapter called “A Few Points of Grammar” to get to his real target, “questions of artistry” (p. 1). So far, so good, but problems soon develop around many of these nodes. The level of audience assumed by the book frequently varies. The book functions in many passages as an introduction to various classical arcana of questionable utility. Even more than questions of artistry, Clark deals with “questions about style” that are “questions of taste” and so “do not have definitive answers.” As many critics before him, he claims that “taste can still be discussed” (p. 14). The question is, “How?”

Technical Writing Rules You Didn't Learn in RHET 101

To hyphenate or not to hyphenate, that is the question. As compound nouns evolve over time in Eng- lish, they gradually move from being written 'open' (data base) to being hyphenated (data-base) to being written 'closed' (database). Just where your particular word might be in its evolution is often un- clear and subject to the inscrutable and highly individual logic of copy editors. Consult a recent edition of a standard dictionary.

Design Guidelines for Written Assignments

This paper discusses design guidelines educators can use to format their assignment instructions. The purpose of formatting is to avoid students' misinterpretation of the assignment and to receive more readable papers. Topics covered are design awareness and formatting tips on using headings, chunking information, and using special features.

Understanding the Importance of Style Guides

Style guides describe conventions for virtually every aspect of writing, ranging from such things as spelling, punctuation, and word usage, to structural and formatting issues. With the myriad of style guides in use, the dilemma for many writers is deciding which one to learn and apply in the trade. The answer to this is easy: learn at least one style guide thoroughly and keep a selected few others for backup. In the course of recruiting technical and generalist writers and editors for nearly a decade, I am sometimes shocked at the low level of familiarity with long-established style guides by people who claim to be seasoned professionals in this business. The reality is that it is plainly obvious to spot writers who “claim” to know a style guide and those who have actually taken the time to study it. The proof is in the pudding, as they say. The quality and consistency of a writer’s or editor’s output is the litmus test to how proficient he or she is in applying a given style guide.

Documentation through the Discovery Process

Kloss describes a process of composing documentation that requires the writer's involvement at every phase of product development.

Elegant Documentation

Blank discusses the benefits of using consistent styles in documentation.

Still Another Rule?

Bush questions the wisdom of rigid grammatical rules that do not take into consideration the complexities of English.

The Style Guide is Dead: Long Live the Dynamic Style Guide

Arguing that printed style guides are too static to be useful, Hart recommends using a dynamic style guide, a system of templates, macros, and reference materials that actually guides writers through their work. The article also advocates direct interaction between editors and writers as a non-technical approach to a dynamic style.

Developing a Departmental Style Guide

As a technical writer, you may be asked to develop a style guide for the hardcopy and online documents you produce. Sounds easy enough. After all, commercial style guides and, potentially, examples shared by your colleagues should provide enough information to get you started. In researching your task, though, you may find a variety of definitions and explanations of what a style guide is and why companies use them. What's more, you many find that style guides don't seem to have consistencies among them that can help guide you in developing one.

Master Documents

This chapter ventures deeply into Microsoft heresy. A heretic is someone who preaches heterodoxy, or mixed doctrines. Unlike a lot of official MS and MVP speak, this topic advocates the usage of a certain feature that can be said to be generally considered as broken - Master Documents, or Masters. As so little information is forthcoming on this subject from other sources, yet many writers use them regularly because there is no other choice, it is fully covered here.

The Passive In Technical and Scientific Writing

Almost every discussion of technical or scientific style mentions the passive voice, usually as a stylistic evil to avoid. While I doubt that many of us would endorse such extreme prescriptions as 'Always use the active voice,' or 'A writer will almost automatically improve his style when he shifts from passive to active constructions,' we may be more ready to accept Freedman's position in 'The Seven Sins of Technical Writing.' His Sin 6 is 'the Deadly Passive, or, better, deadening passive; it takes the life out of writing, making everything impersonal, eternal, remote and dead,'3 but he adds that 'frequently, of course, the passive is not a sin and not deadly, for there simply is no active agent and the material must be put impersonally.'

The Rhetoric of the Paragraph: A Reconsideration

Efforts to define the fundamental structures that enable meaning in discourse have a long history, beginning with ancient speculation. Classical logic, rhetoric, and grammar imposed restrictions on the processes of composing, as well as the shapes of finished texts, in order to safeguard the truth by attending to prerequisites for its effective communication. From earliest times, a concern for vindicating some larger moral order, and for teaching others to appreciate it, has often motivated pronouncements on the nature of verbal form. From Quintilian to the present, for example, teacher-scholars have striven to insure that logical and aesthetic values celebrated in the classical doctrine of decorum are made suitably manifest in student performance, as though to enforce publicly accepted styles of thought and action by reference to acceptable forms of language.

The Grammar Instinct

Back in 1990, Leonard and Gilsdorf presented 45 instances of questionable usage, in full-paragraph contexts, to both academics and working business executives. These usage elements included sentence fragments, assorted punctuation problems, pronoun–antecedent (dis)agreement, and various examples of questionable word choice. Their intent was to assess the “botheration level” of each usage “error”; their conclusions were that 1) academics are (nearly) always bothered by usage “errors” more than executives and 2) usage elements that bothered survey respondents the least were evolving over time into acceptable English usage. Just over ten years later, these same researchers have followed up on their original study and have drawn similar conclusions from the more recent data.

Grammar, Punctuation, Spelling

The Web abounds with sites teaching grammar, punctuation, and spelling. Not surprisingly, most of these sites are provided by educational institutions, teachers, or business-writing consultants, presumably to make up for the lack of grammar teaching in so many school systems for the past several decades. Some are tutorials (masquerading as style guides) for technical communicators. Here are a few sites that I have found useful or that other people have recommended to me.

Gender-Neutral Technical Writing

Gender-neutral writing uses language that does not stereotype either sex nor appear to be referring to only one sex when that is not the writer's intention. In this article, you'll see why gender-neutral writing is important for technical writers to use, what gender-neutral writing is not, and how you can use gender-neutral writing in the documents you develop.

Guidance on Style Guides: Lessons Learned

This article highlights some of the lessons that I’ve learned about the process of creating style guides and implementing processes for ensuring that a product is consistent in a number of dimensions. I discuss the purposes and benefits of a style guide, a process for creating a style guide, the many types of consistency, reasons why style guides fail, methods for ensuring consistency, and some references that discuss these issues in more detail.

Using a Style Guide to Build Consensus

Style guides are often requested as a way to promote a common look and feel but do little to address the real problems in the way user interfaces are developed. In many situations, a collection of rules for visual design and the use of controls can seem like a band-aid; promoting surface-level consistency rather than solving the real usability problems. Even when a good style guide is created, it is often ignored after release. Worse, the style guide can become a weapon where a user-centered design process is needed. In either case, the style guide has failed to produce the desired effect. What’s missing is a consensus on the scope, ownership, or content. Solving this problem requires a change in the way style guides are developed, distributed, and used. Three suggestions for teams developing style guides are to start early, to make the emerging style guide widely available, and to plan for long-term maintenance of the guidelines.

Tips for Technical Writers

Begin by getting familiar with your corporate style. If there is no existing style guide, either review existing manuals to determine what has been done in the past ( Pay special attention to the language, assumed prior knowledge, general organization and presentation of how-tos (task-based or informational)) or choose a style guide.

Editing for Gender Neutrality

How to be politically correct without mangling the English language. The goal is that the reader should not notice the writing.

But the Stylebook Says...

You might think a chapter about how to read a dictionary is a waste of paper, but you'd be wrong. Stylebook entries are designed to be even more explicit in their explanations than dictionary definitions are, but writers and editors still manage to miss the point. When members of the American Copy Editors Society were asked to cite examples of often-misused words, John McIntyre of the Baltimore Sun nominated 'stylebook.' The most common form of stylebook abuse is the use of an affirmative entry as a negative entry. Boneheaded editors see x in the stylebook and decide that means they must never, ever use y. A lot of stylebook entries do work this way, but the authors of the stylebook are giving us a little credit and figuring that we can tell which y they're discouraging. One entry, for example, reads 'spaceship.' This doesn't mean all other words in the language are banned; it means simply that AP does not use 'space ship' as two words.

When Metaphors Fail to Keep Their Distance

Was I being too literal when I made the following change? I don't think so. A name-brand financial columnist wrote the following paragraph in a piece about Web-based credit cards: Most issuers mail you a plastic card, usually a MasterCard or Visa, which you also can use in stores. At Citibank, however, plastic has become uncool. Instead, it's offering ClickCredit, a virtual card (www.clickcredit.com). It acts like a credit card, but exists only in Citi's computer. You use it solely for making purchases on the Web. The problem is, I have one of these Citibank cards, and while it's true that it's not an ordinary credit card that you carry around in your wallet and use at stores, it's also true that the ClickCredit people do mail you a card, and it's made of plastic.

Disciplinary Style Manuals as Reliable Guides to Scientific Discourse Norms

Style manuals sponsored by professional associations in various scientific disciplines have received virtually no scholarly attention. These manuals, however, specify many disciplinary discourse norms that writers need to follow in publishing scientific research. Consequently, these manuals provide an important and reliable source of information about how communities of working scientists conceptualize, construct, and publish their scientific texts. The disciplinary norms that these style manuals promulgate derive both from general scientific research practices and from the practical demands of scientific publishing. Because of their unique normative nature and their connection with scientific practice, disciplinary style manuals should be categorized separately from other types of scientific style manual, and the material they contain can reliably be used in technical writing and editing.

The Scientific Style Manual: A Reliable Guide to Practice?

Is the scientific style manual a reliable guide with regard to the organization and content of the typical scientific article? The answer is, yes and no. Style manuals do provide much sound advice based on their authors' personal experience. However, they also pass on some advice at odds with recently published literature regarding how scientists actually conduct research and write up their findings. This article presents a revised model for the scientific article, a model base don information in recently published research on communication in science.

User Attitudes Toward Corporate Style Guides: A Survey

Little information is known on user attitudes toward corporate style guides (CSGs). A national survey shows that an overwhelming 93% of users and 85% of non-users advocate CSG usage primarily to generate consistency in documents, to save time generating documents, and to create a professional look in documents. As corporations face the future by restructuring, usually by downsizing, and by competing more in a global economy, CSG usage will be more prevalent in corporate America, as the results of this survey indicate that CSGs are an economical quality tool that benefits both the user and the corporation.

Online Style Guides: Getting Past Caps and Commas

Style, and style guides, are perennial hot topic in the online content business. Many content professionals seem preoccupied with finding the ultimate, authoritative source with the final word on whether 'Internet' should be capitalized, or whether 'Web site' is one word or two. But in reality, such questions are among the least important concerns of online style. Where you put the punctuation doesn't matter nearly as much as how you shape and deliver your messages.