Yale University

Communications | Web publishing

General editorial guidelines for web content

Suggested guidelines, particularly for sites with technical content. Many Yale departments maintain their own more discipline-specific editorial guides, so check with your department for proper usage guidelines.

Writing and language guide

Content guidelines are presented in alphabetical order by topic.

Abbreviations & acronyms

An acronym is a pronounceable word formed from the initial letter or letters of major parts of a compound term. An abbreviation is usually formed in the same way but is not pronounced as a word.

Abbreviations are often lowercase or a mix of lowercase and uppercase. Acronyms are almost always all caps, regardless of the capitalization style of the spelled-out form.

  • Abbreviation example: “St.” for street
  • Acronym example: SAN—storage area network

When and how to spell out abbreviations & acronyms

In most cases, spell out an abbreviation or acronym on its first occurrence in a document. If a document has more than one chapter, spell out the abbreviation or acronym on its first occurrence in a chapter. On a website, spell out the term at its first appearance on a page.

When you spell out a term, put the definition first, with the abbreviation or acronym in parentheses.

File type abbreviations

Use all caps for abbreviations of file types. For example, a JPEG file, an AIFF file, the MP3 file.

Filename extensions, which indicate the file type, should be in lowercase. For example, .jpg, .gif, .mp3.

Active voice

Use active voice as much as possible, use a subject that tells who or what is performing the action.

Examples:

  • Active voice: Use the Name field to enter your name. You can store up to 500 files in the database.
  • Passive voice: The Name field is used to enter your name. Up to 500 files can be stored in the database.

Ampersand

You may use an ampersand in a title heading or in a list of links when space is at a premium. Otherwise, use the ampersand character (&) in text only when you describe a command name, an onscreen element, or a document title that uses the character.

On the web the ampersand character has a special function in designating character entities, and should always appear in XHTML page code as the character entity “&” to avoid code validation problems.

Boldface type (Strong emphasis, <strong>)

To enhance the semantic meaning of your web content, always use the XHTML tag “strong emphasis” (<strong>...</strong>) to make words in boldface type within your content. The <strong> tag is styled to render text in boldface within the ITS site.

Use bold (strong emphasis) to indicate the names of user interface items including buttons, dialog box, and window names.

Capitalization

Use sentence-style capitalization for text headings (for example “Installing the software”).

Dialog box

A dialog box is a type of window that typically comes up when more information is needed to complete a command. The correct way to refer to using a command that brings up a dialog box is to refer to the command, not the dialog box.

Correct example:

You can use the “Find” command to search for this text.

Incorrect usage:

You can use the “Find” dialog box to search for this text.

Figures

Diagrams, photographs, and screen shots are all considered figures. You should use figures when their presence enhances the reader’s understanding or illustrates a procedure or point that is not evident from the text alone.

Don’t use captions for figures. Pictures tell a story. If a figure seems to need a caption to explain what it is about, you should consider using a different figure.

Headings & organization

Use levels of headings to make the organization of the document clear, but remember that too many headings too close together distract the reader and clutter the page.

Organize your sections so that level-two heads are subordinate to level-one headings, level-three headings to level-two headings, and so on. Use headings to define structure, not because you want to use the font or text style assigned to the heading style.

Parallelism

Keep the wording of headings within a section parallel:

  • Use the same verb forms (gerunds, imperatives, and so on) from head to head.
  • Comparable terms should all be either singular or plural, not a mix.
  • If you use complete sentences for some heads, use them for all comparable heads.

Correct example:

  • Open the book.
  • Read the text.
  • Look at the pictures.

Incorrect:

  • Open the book first.
  • You must read the text now.
  • There are pictures in the book – Look at them

Lists: Unordered or “bullet” lists

Lists can make text content easier to scan. Lists are also very important semantically in web search and content accessibility, as a list indicates that a series of items are related in meaning.

Unordered (“bulleted”) lists

A bulleted list can often make a complicated sentence into a simple enumeration of critical points.

Example (easier to read)

This document includes several sections:

  • User interface
  • External interfaces
  • Data model

Example (harder to scan quickly)

This document includes several sections. The first section describes the user interface. The next section describes the external interfaces. The last section describes the data model.

Guidelines for bulleted lists

  • If some of the items in a list are sentences, make all the items sentences.
  • If some of the items in a list end with punctuation (for example, a period), end all of the items with the same punctuation.
  • If some of the items in a list begin with verbs, begin all items with verbs.
  • In short documents, try to structure all your lists the same way—either sentences or not.

Lists that are ordered by number or letter

Ordered lists are semantically important for web search and content accessibility, as they indicate that a series of items are both related, and in a particular order of priority or sequence.

Use a numbered list when you want to stress the sequential nature of steps, rules, or instructions. Numbered lists, which have the same syntax as bulleted lists, are useful when:

  1. You want to indicate that the order of items in the list is significant.
  2. You want to be able to refer to particular list items by number or letter.

Example of an ordered list, by number

  1. In HTML lists can ordered by various number and letter designations
  2. A plain <ol> tag produces a numbered list
  3. Use <ol type="a" > for an list ordered by lower-case letters
  4. Use <ol type="A" >, for A,B,C,D
  5. Use <ol type="I" >, for I,II,III,IV
  6. Use <ol type="i" >, for i,ii,iii,iv
  7. Use <ol type="1" >, for 1,2,3,4

Notices: (“Note,” “Important,” or “Warning”)

Use notices sparingly—they lose intended impact if they appear too often.

  • “Notes”—Use a “Note” heading for information that is relevant to a topic but that may not apply to all readers.
  • “Important”—Use an Important notice to alert the reader to likely trouble spots
  • “Warning”—Use only where the is a significant chance that a user will lose data, damage hardware, or might be physically injured.

Plurals

Don’t add an apostrophe before the s when you form the plural of an abbreviation.

Example (correct): CDs, ICs, ISPs.

Acronyms

Add an ‘s’ but no apostrophe: PCs, DVDs.

 

 

Jump to top.

Last modified: Friday, 12-Feb-2010 11:06:33 EST. (pl)