This document contains guidelines for the text and graphics that appear in Open Market product screens.

General Goodness and Virtue in Prose

1. Use active voice; avoid passive voice. For example, consider the power of the active voice in the following sentence: "Carifio smacks the wayward engineer." Now, here's the same sentence in passive voice: "The wayward engineer is being smacked by Carifio." Converting to passive voice robs the sentence of its power. Passive voice also makes the sentence longer, trickier to understand, and harder to translate.
2. Use the language of your audience. For example, the phrase "I/O" is appropriate for programmers, though "Input and Output" would be a better choice for nonprogrammers.
3. Use present tense.
4. Use simple words. As Strunk and White might say, don't use a five dollar word when a fifty cent word will work just as well.
5. Be brief, so that the user doesn't need to scroll.
6. Don't state the obvious. (Is this a self-violating rule?) For example, avoid explanations like, To continue, press the Continue button.
7. Present information relevant to the current context only. Don't tell the user that her Cosmo subscription is about to expire when she's trying to get to her New Republic subscription. Nor is she interested, at that point, in problems with payment for her Old House Journal subscription.

Error Messages

1. Don't use prefatory text to announce that error messages will follow. For example, a screen should not say something like, "You made the following errors:" Instead, the screen should simply present all the error messages.
2. Use the triangular-with-exclamation-mark symbol to flag the user that there are some errors to attend to. I need the pathname to this bitmap.
3. If there is more than one error message, place a number by each message. The first number should be 1 (never 0). (Barry's editorial comment: This violates one of the basic tenets of tech writing, which is that unordered lists should be bulleted rather than numbered. Error messages are typically unordered; they should get bullets rather than numbers.)
4. If there is only one error, put a bullet (not a number) in front of the error.
5. If there are zero errors, should UI indicate success?

HTML Formatting Suggestions

1. Don't use the HTML ‹blink› directive. Blinking gets annoying quickly.
2. Use the HTML ‹emphasis› directive for emphasis; don't use all uppercase letters to emphasize. All caps makes for hard reading.
3. Match the name of an anchor to the heading name on the target page.
4. Left-justify text; text is more readable that way.
5. How about headers; should they be left-justified, too? Should top-level headers be centered?
6. Should the title exactly match the top-level header?

Writing Text That Translate Well

Even as we speak, citizens of other nations are crying out for Open Market products. Though we North Americans have tried for years to eradicate other languages, it seems that small pockets of resistance are still smoldering in the mixed metaphors of our melting pots. At any rate, translators will soon be converting our golden English prose to other languages. To make our translators' task easier, please follow these guidelines (courtesy of William Horton):

1. Avoid prepositions in short phrases, such as on a menu or bulleted list.
2. Minimize abbreviations and acronyms. Hey, would it really kill you to type out Digital Offer instead of DO?
3. Be as brief as possible to avoid translation expansion problems. English is a relatively terse language; English text often expands considerably when translated into other languages. Therefore, English text that barely fits onto one screen will probably overflow one screen when translated into French.
4. Avoid slang. Although our products are way cool, describing them as such may cause our Japanese translators to describe them as being best run at low temperatures. American slang comforts American readers but rarely translates well.
5. Use conventional syntax.
6. Localize formats for
   • numbers
   • dates
   • times
   • addresses
   • phone numbers
   • amounts of money
   • units of measurement
   • order of family and given name in polite society

   But how do we at Open Market actually localize these formats?

   Buttons

   1. Don't use "Yes" and "No" buttons– the buttons should explicitly describe its action. For example, the following buttons are far safer than simple "Yes" and "No" buttons:

      Are you sure you want to delete the root directory?
      
            [Delete directory] [Return without deleting]
      

   2. How should buttons look? Should they always be rectangular? What background color should they have? What size font should be used for the text? What color font? Should they be arranged vertically or horizontally?
   3. Graphically distinguish default action buttons. On any page, one button should be the default or desired action. That button should be graphically distinguished (outlined, color, something...) to prompt the "right" action. This recommendation seems kind of vague. Shouldn't you standardize the graphical distinguishing point?
   4. Hyperlinks in text (href="xyz.html") should go to information; buttons should take action on behalf of the user. For example:

      The button [Become a Member] should transfer control to a membership registration screen. By comparison, the hyperlink ‹a href="..."› Become a member ‹/a› should transfer control to a screen that explains everything there is to know about memberships.

   5. Buttons must always be rendered through bitmaps (‹img› directives). Rendering a button as a graphic is slightly slower than redering it as text, but we've decided that the very slight performance hit is worth it.

   Fonts

   1. The latest Microsoft browser allows content providers to specify font families. Which fonts should Open Market use?
   2. Use font sizes larger than 9 pts. Though we tend to think of the Internet as dominated by smarmy 14 year olds, remember that people with bifocals use the Web, too.

   Colors

   1. Can we provide exact values for the alink, bgcolor, link, text, and vlink attributes of the HTML ‹body› directive?
   2. Avoid soft blue text for hyperlinks; soft blue text is difficult for older persons to read. Consider using other colors, or choose a strong blue. If you use a textured background, make sure that the blue is not faint.
   3. What is our policy on textured backgrounds?
   4. Use colors that do not clash with labels. A Go button should be green, not red. Text and color should have a consistent relationship.

      General UI Tips

      1. Be humble. Assume that this screen is relatively unimportant in the reader's grand scheme of things.
      2. Be predictable. Be consistent. Don't surprise the user.
      3. No news is great news. The most successful interfaces go unremarked; users do not complain, they just get their work done.
      4. Don't give instructions; no one reads them. Design until you don't need instructions. Or need so few that they will be read (maybe).
      5. Always give the user a way to continue, go back (the Back button doesn't count), and/or exit. Just curious: why doesn't the Back button count?
      Revision History

      Rev	Date	What Changed
      1.0	~July	Margaret's original version
      1.1	Sep 11	Marjorie converted doc to HTML
      2.0	Sep 16	Barry reorganized and added Mary's WebNotes on style