The Yahoo! Style Guide: a review
Review by Mike Unwalla.
Chris Bar and the senior editors of Yahoo!, 2010. The Yahoo! Style Guide. London, Macmillan. 512 pages. ISBN 978-0-230-74960-3.
"What is a tribble, and why is a tribble difficult to control?" is one possible question from readers of The Yahoo! Style Guide. In a style guide from a global company, I expect internationalized content. Readers who do not know American culture will struggle to understand some of the content. (For information about tribbles, see Wikipedia [https://en.wikipedia.org/wiki/Tribble].)
The Yahoo! Style Guide explains how to write for an international audience. But, the text does not conform to the guidelines that are in the book. Possibly, many readers of the book read English as a second language.
The Yahoo! Style Guide has some irritating errors, as the following examples show:
- "It's impossible to write without using some idioms" is not correct.
- "You can find out how many people opened your [e-mail] message" is correct only in some situations. For example, an HTML e-mail can contain a tracking image, but if the e-mail is viewed as plain text, the sender will not know that the e-mail was opened.
The chapters in The Yahoo! Style Guide are organized in sequence from less technical to more technical. Ideas are introduced early in the book, and are discussed in detail later. For that structure to be satisfactory, readers must know where to find information. For the best user experience, a better index is necessary. Sometimes, related information is in too many different locations.
Despite my criticisms, The Yahoo! Style Guide is useful. Although I do not agree with some of the guidelines, I learnt new things.
The Yahoo! Style Guide is designed for bloggers, editors, technical writers, video producers, and other people who create content for Yahoo! However, most of the content is applicable to all people who write online content.
The Yahoo! Style Guide is much more than a style guide. The book has guidelines about words and grammar, but the book also is about accessibility, audience analysis, text for headings, HTML, search engine optimization, the design of user interfaces, US copyright law, and many other topics. Therefore, 'The ultimate sourcebook for writing, editing, and creating content for the digital world' is an accurate subtitle.
The book's related website [http://styleguide.yahoo.com] contains the table of contents, some content from the book, and additional resources.
The book's 19 chapters are organized into six sections. In the remaining part of this review, I discuss some of the book's content.
Section 1: write for an online audience
The Yahoo! Style Guide starts with simple guidelines such as use simple words, use simple sentence structures, and have clear navigation. Readability is important. The Yahoo! Style Guide recommends that writers use readability statistics. However, The Yahoo! Style Guide does not explain that a good readability score is not sufficient to make text easy to read (https://irp-cdn.multiscreensite.com/aaf9e928/files/uploaded/Towards_A_Better-Readability_Measure.pdf).
To write well, a writer must know about the readers. Unlike most style guides, The Yahoo! Style Guide has a chapter about how to identify the audience. To write for a particular audience, define a voice that shows the 'personality' of a website. The voice is a special style that makes a website different from all other competing websites.
Section 2: speak to your entire audience
A writer's primary task is to write for the audience. But, do not think that only the target audience will read a website.
The Yahoo! Style Guide recommends that writers use neutral language. For example, do not use unnecessary references to gender.
Because readers possibly are from all parts of the world, write for an international audience. The guidelines are good, but with only 20 pages including an example, many technical details are not included. For detailed guidelines about grammatical structures, a better book is The Global English Style Guide by John R Kohl.
Millions of people who use the Internet have disabilities. Chapter 6 explains how to make a website accessible to all visitors. The guidelines are about both the text and the structure of a website. For example, CAPTCHA helps to prevent spam on blogs, but if an alternative is not available, blind people cannot give their comments.
Section 3: write UI text, e-mail, and mobile-friendly content
In The Yahoo! Style Guide, the term user interface means the parts of the design that help people to navigate a website. A user interface includes things such as buttons, links, help pages, and error messages. Two important guidelines are as follows:
- Use the same term for the same thing. "Don't call a feature a 'Shopping Cart' on one page, a 'Cart' on another page, and a 'Shopping Basket' on a third." This guideline is sufficiently important for the book to have a chapter that tells writers to keep a word list.
- Create written 'signposts'. Signposts help readers to navigate around a website. Examples of signposts are 'Next' and 'Previous' links.
Online help and FAQs are part of the user interface. The Yahoo! Style Guide explains how to write clear FAQs. However, a better option is to structure a document such that FAQs are not necessary.
The screens on mobile devices are small. Readers do not want unnecessary words or unnecessary images. The Yahoo! Style Guide gives methods to make text as short as possible. In one example about a restaurant, a paragraph of text is changed to a list of keywords. For example, a 34-word sentence becomes "What to order: Spicy Cold Sundae, lychee jellydim-sum donuts". I think that although the method is satisfactory for the example, mobile devices are not suitable for some types of information.
Section 4: manage the mechanics
Section 4 has similar content to most style guides. For example, punctuation, abbreviations, and styles for numbers are discussed.
Most style guides agree about basic guidelines. But, style guides do not always agree about technical details. A good example of a contradictory guideline is to "use a comma after an introductory phrase that is four or more words long".
The Yahoo! Style Guide does not explain the reason for the guideline. Possibly, a comma after three words or after five words is better than a comma after four words.
The Economist style guide gives a reason, "It is not always necessary to put a comma after a short phrase at the start of a sentence if no natural pause exists there… But a breath, and so a comma, is needed after longer passages…"
However, The Oxford Manual of Style states, "Adverbial material, whether clauses, phrases, or single adverbs, obeys no single rule regarding commas… Adverbs and adverbial phrases that comment on the whole sentence, such as therefore, perhaps, of course, are often enclosed in commas… Do not introduce a comma between subject and verb, or verb and object—even after a long subject, where there would be a natural pause in speech, if only for breath." (The Oxford Manual of Style is now The Oxford Style Manual.)
Section 5: clean up your copy
Many style guides tell writers to write clearly and simply. The Yahoo! Style Guide has an excellent visual example:
Chapter 13 emphasizes that short and clear sentences are important. Most of the guidelines are standard 'plain English' guidelines. For example, use the active voice, remove unnecessary words and phrases, and do not use clichés.
Because the chapters in The Yahoo! Style Guide are organized in sequence from less technical to more technical, each topic is discussed in more than one location. To find information, a better index is necessary. For example, in chapter 13, the first paragraph in 'Cut length–not clarity' is as follows: "Some small words that seem unnecessary to native English speakers may be cues that aid comprehension for people less fluent in English. If your audience is likely to include nonnative speakers, follow these guidelines to retain cues that aid clarity."
The text discusses words such as 'that' and 'then', and refers readers to chapter 5 for more information about how to write for an international audience. Chapter 5 uses the term 'signpost' for what John R Kohl calls 'syntactic cues'.
In the index, I searched for words that are in the text, and for synonyms. Eight terms that I looked for are not in the index. The terms international audiences and signposts do not help to find the information that is in 'Cut length–not clarity'.
Unlike most style guides, The Yahoo! Style Guide has a chapter about how and why to proofread. Error-free text is important, because errors decrease the credibility of a website (https://credibility.stanford.edu/guidelines/). One method of proofreading is to read text aloud. An interesting alternative is to use screen-reading software.
Section 6: resources
Writers do not need to know HTML or XHTML, but basic coding skills can be useful. For example, many times, I see web pages in which characters do not display correctly. The Yahoo! Style Guide explains why the problem occurs, and how to make sure that characters appear correctly.
Many people search for information using a web browser. Therefore, optimizing a website to get a high search engine rank is important. The best keywords are multi-word terms, because there is too much competition for one-word keywords. Text, images, and video can all be optimized. For example, for an image file, use an applicable keyword in the name of the file.
To make sure that the style is the same for different documents, keep a word list. The Yahoo! Style Guide gives writers general advice, but it cannot give writers advice about an organization's terms and editorial preferences. A word can have different spellings, for example, acknowledgement and acknowledgment. If a website uses different spellings, some readers will not trust the website.
According to The Yahoo! Style Guide, "Consistency is relatively easy to achieve in print or on a website where you're the lone writer." I do not agree. To make sure that term are used with their specified meanings is difficult.
The Yahoo! Style Guide continues, "But the degree of difficulty multiplies when many people contribute content and when the site grows continually." The Yahoo! Style Guide gives some methods that help writers to solve the problem. However, to solve the problem fully, software is necessary. Here, The Yahoo! Style Guide could discuss controlled vocabulary, controlled languages, structured writing, and language quality-assurance.
See also 
Reviews of books that are about English for international readers
RSS feed