Writing for the Web: Guidelines for MIT Libraries: Writing guidelines

Public web guidelines

Writing for the Web tips recording & slides 

House style guide

For more information:
Contact UX/Web services

1. Call attention with useful headings.
2. Catch the user in the first few words.
3. Be human! Lose the formality.
4. Use consistent punctuation, capitalization, and spacing.
5. Use lists.
6. Give instructions with imperatives.
7. Use parallelisms.
8. Use words users know.
9. Try fragments.
10. Make links descriptive.
11. Use shortcut links.
12. Format links properly.

Headings catch the eye

When users scan a page, headings are usually what first grabs their attention

What should a heading look like?

Questions or statements work well as headings. They draw the user into the text.

Headings

What did you expect to find under this heading? Nouns are less informative as headings.

Users skim:

• They may start to read, but they also stop quickly unless the writing captures their interest.

Think journalism (not academic writing)

• Who, what, where, when, why and how
• Start with the conclusion, then give the details

No need to be too formal! Write what you would say to them if you were talking on the phone. 

Think in short stories (scenarios):

• Write in terms of "who does what to whom."
• Use active voice, personal pronouns, action verbs, & contractions.

When users "think aloud" through a paragraph in typical academic style, they translate the passive, noun-based writing into scenarios.

Consult the MIT Libraries House Style Guide for details.

In short:

• Oxford commas: Use them! (ex. "red, white, and blue" NOT "red, white and blue")
• Single-space after periods.
• Capitalization:
  • For blog titles and LibGuides box titles, capitalize only the first word. 
  • For web page or guide titles, capitalize only the first word.
  • Always capitalize proper names!
• Sentence case vs. title case example: 
  • Yes: Open access downloads: February 2022
  • No: Open Access Downloads: February 2022
  • Yes: MIT Reads Virtual group discussion
  • No: MIT Reads Virtual Group Discussion

Lists:

• facilitate scanning
• create chunks
• separate ideas
• show relationships
• allow counting
  • Use numbered lists for steps that must be taken in a certain order.

Think about the order. If some list items are more important, put them at the top of the list.

To make instructions easy for users to follow:

• Use numbered lists.

• Use imperatives: "Do this."

• Put some space between the steps.

People like patterns

• We grasp the information more quickly if we can anticipate the pattern.
• We try to see patterns in information even when there are none.
• When we have to switch patterns, we use extra mental energy.

Your audiences are almost always broader than you think.

• If your site is for the public, avoid internal language.
• If your site is internal only, consider how many different audiences you have inside.

Use simple words

Even highly educated people read simpler words faster.

Also, consult the MIT Libraries House Style Guide for commonly used terms.

Space is always at a premium.

• Complete sentences are not always necessary.
• Distinguish between:
  
  • fragments - coherent phrases
    
  • telegraphic writing - leaving out words like "a" and "the"
• Telegraphic writing may be OK in navigation, but avoid it in text. It doesn't save time because the user has to mentally put the little words back in.

Links that are descriptive are more useful than links that name categories.

• Words must be informative - not fluff.
• Use the page title in your link.
• Action words and imperatives serve as calls to action (ex. "Renew books").
• Never say "click here..." 

If you're linking to a popular page on the Libraries' website, check the shortcuts page. If you find a shortcut URL, use it!

Why?

• When we have a web site redesign, shortcut URLs won't break. 
• Shortcut URLs looks better.

Don't show URLs unless there's a really good reason.

An exception might be a "get" URL if you want people to bookmark it. If you do show the URL, don't include the "http://" in the text.  (But do include it when you hyperlink it, so the URL works!)

Keep it clean!

Only underline the text you're linking, not spaces before and after the link. In some systems, the underline will look hyperlinked, and that looks sloppy!

Examples:

• Wordpress: See the first link in this new blog story.
• LibGuides: Hover over this link!