Web Writing Style Guide

← Web Content Guidelines

What is good web writing?

Good web writing:

• is like a conversation. Think of your content as a focused conversation started by a busy person. When users come with questions, you provide answers. When users come to do a task, you help them. But because you aren't there in person, you have to build your side of the conversation into the site.
• answers people's questions. If you think of the web as a conversation, you'll realize that much content is meant to answer people's questions. You do not want pages of FAQs. You do want to think about what people come wanting to know and how to give them that information as concisely and clearly as possible.
• lets people grab and go. Breaking information into pieces for different users, topics, and needs help patrons grab just want they need and go on to look up their next question, do their next task, make a decision, or whatever comes next.

Web writing is more informal than other formats. For the Duke University Libraries, you should aim for a voice that is clear, credible, trustworthy, and welcoming.

Our web content is an extension of our interaction with users. We also apply our User Service Philosophy to web content.

Focus on essential messages

Most people come to the web for information, not for a complete document. They don't want the user manual; they want instructions for the task they are doing. They want usable, manageable pieces.

Ginny Redish,  Letting Go of the Words

Give each page a clear and descriptive title.

If your page is frequently linked from another place, the page title should should match the text link as closely as possible. They should also clearly describe the subject of the page.

Don’t waste space welcoming people to the page.

There is no need, and most users ignore any welcome text as filler.

Write information, not documents.

Ask if your web page is too long, and whether it should be broken down into separate, linked pages.

Your first paragraph is the most important one.

It should be brief, clear, and to the point in order to engage the user. One-sentence paragraphs are encouraged.

Put important information and tasks first.

Follow the top-to-bottom hierarchy, saving less important information for last.

 

Web users trying to grab and go prefer inverted pyramid style to traditional narrative style (Redish, 2007)

Use short paragraphs.

Large blocks of text look like walls to the user. Research has shown that short, concise paragraphs and bulleted lists work best for web use.

Just say it.

Phrase things in simple, straightforward language, using familiar words and avoiding jargon.

Style and tune up your sentences

Use these guidelines for writing style

• If you are telling people something about themselves, talk to users. Use "you."
• When referring to yourself or the Libraries, use plural pronouns: "we", "us."
• Define unfamiliar terms. Many terms we use in the library world are unfamiliar to outsiders. Don't expect everyone to understand. When in doubt, put a brief definition in parentheses.
• Avoid acronyms and abbreviations, except when they are significantly shorter or common parlance. (Common parlance among librarians doesn't count.)
• Be consistent. Use the same word or phrase to describe the same thing, and always spell it the same way.

Use these conventions for grammatical choices

• When listing items, use the serial or Oxford comma.
• Use Title Casing for the top-most title of the webpage. This is where Drupal asks you to list a required "Title*" above the page content.
• Use Sentence casing for subsequent (H2, H3) headings.
• Use one space between sentences, not two.

Use emphasis rarely and with intention

• Use bold sparingly. Bold should be used for headings and then sparingly for any other emphasis.
• Italics should also be used sparingly. Avoid making long paragraphs italic – you are making the text harder to read, not giving it emphasis. Exceptions are book titles.
• Do not underline text. On the web, underline means a link.
• Use all caps sparingly. Research shows that all caps are harder to read than mixed case.
• Don’t emphasize too much. If you use bolded headings, short paragraphs, and bulleted lists, you should not need to rely on italics, all caps, or underlining for emphasis. These styles can make the page look messy and compete for the user’s attention.
• Avoid exclamation points. We all know Duke is awesome! We love it! But let the content speak for itself.

Use headings to break up text

Using headings is a critical part of good and accessible web writing. Headings allow users to determine what a block of text is about before they invest time to read it.

• Make sure headings are tagged properly in HTML as H2 or H3. Do not style body text manually to look like a heading.
• Good headings are not trivial to write! Consider headings that are (1) questions that users may have or (2) statements or key messages.
• Ideally, use noun and noun phrase headings sparingly. For instructions, use action phrase headings.
• Do not use more than two levels of headings (below the title). In Drupal pages, use H2 and H3 for sub-headings, as titles are H1.
• Write the heading with words that users already know. Avoid unfamiliar terminology.

How do you know if you have good headings?

1. Read only the headings on your page. Do you understand what each heading means by itself?
2. Do the headings tell a coherent story?
3. Do they successfully give you the big picture? Can you get the gist of all the information from the headings?
4. Do they distinguish different sections? If you wanted only some of the information, is it clear where you would go for that information?

Write meaningful links

• Link, link, and link to relevant information. If you mention a summer reading program, link to it. If you mention a faculty member, link to their bio page. Don’t make people search for something that you mention if it already has a page.
• Make your links contextual. Use part of the actual referencing sentence as the link. Research shows that users like them to be 4-8 words in length.

Do not use: For interlibrary loan information click here.

Do use: Interlibrary loan information is now available.

• Avoid burying links. Placing a link in the middle of a block of text is a good way to keep people from seeing it. Instead, consider placing it at the top, the bottom, or on its own line.
• In general, links should load in the existing page ("parent"), rather than open a new tab or window.

Use images effectively

• Images on the web can be used to show an exact item (such as the shirt you are shopping for), illustrate a concept or process (how to check out a book), display a graph or map, or simply convey a mood.
• Whenever possible, use pictures of people interacting instead of abstract building images.
• Make sure you have copyright permissions to use any picture.
• Find ways to style your images in the Visual Style Guide. Images in this page are styled using <img class="img-thumbnail">.

Four places to find images

Source	Description
Duke Libraries Flickr	A variety of Libraries-specific images and events are captured on this public photostream
Duke Webdam	High quality Duke University photography behind Shibboleth authentification; frequently updated
Unsplash stock photos	General stock photos free with a "do-whatever you want" license
The Noun Project	Simple icons for most things you can imagine; check the licenses for icon usage

 

 

 

 

Make content accessible

Good web writing and design makes web content more accessible to everyone. The guidelines above are written with accessibility in mind, particularly with regard to users who are using screen-readers to navigate the web. (What is a screen reader?)

• Excellent headers make web content easier to skim. This is particularly true for users with screen-readers, who can tab through headings to find the information they want. If headings are not embedded in the HTML of the page or document, the screen reader will not be able to identify headings.
• Screen readers can pull out all the hyperlinks on a page. This is one reason why writing informative link titles is important! Imagine scraping a list of links only to yield a series of "Click here"s and "More here"s!
• Avoid posting PDFs on the web to convey content, unless you are sharing a document. PDFs are optimized for print. They can be accessible to screen-readers, but it requires a bit of set-up.
• When posting images that convey substantive information, use alt text in the HTML code of the image to communicate the messages of the images. If the image does not convey substantive information, there is no need for alt text.

Check your work

• All good writing is re-writing. When you think you are done, look again. Cut your text to the most essential messages. Follow Steve Krug's Third Law of Usability: "Get rid of half the words on each page, then get rid of half of what's left."
• As much as time allows: read your work out loud, let the writing sit for a couple days and return to it, or ask a colleague for edits.
• Review the Content Essentials Checklist.
• Verify names, dates, phone numbers, etc., and double-check them for accuracy.
• Keep your content up-to-date. Out-of-date content reflects poorly on the user’s overall opinion of the website and the Libraries. It also makes the information there appear less trustworthy. If you post something that needs to be updated later, mark it on your calendar so you don’t forget. Give yourself the time necessary to update your content.

Get technical and find help

• For simple page layouts, the WYSIWYG (visual) text format will mostly do. For slightly more sophisticated styles, you will likely venture into the land of HTML. Unfortunately, many of the HTML views in the Drupal system are inscrutable and do not contain helpful line breaks. We recommend clicking on the blue HTML button to the right of the style icons when editing HTML ().

Toggle between "what you see is what you get" (WYSIWYG; "wizzy-wig") and other formats here

• Like a style you see in a Drupal page but don't know how to re-create it? If permissions allow, take a look at the HTML page in the "Edit" view. Just don't save any changes.
• Styles shown on the Duke University Libraries Visual Style Guide are curated from a larger selection of Bootstrap visual styles . You can find more ways to style lists there.
• Drupal adds unnecessary spaces after some elements, such as hyperlinks. This is a known bug. They can be removed permanently by editing changing your editing view from WYSIWYG to HTML and not switching back, but this is a time-consuming effort that is not expected of you.
• Stuck, have a question, or just want a second opinion? Submit a ticket to ServiceNow (support.lib.duke.edu), and someone with expertise with work with you. Select "Digital Projects & Web Services" as the category for your ticket.

Additional resources

• Web Style Guide, 3rd Edition (full-text online) by Patrick J. Lynch and Sarah Horton
• Chicago Manual of Style Online (electronic resource: Duke access only)
• Don't Make Me Think: A Common Sense Approach to Web Usability, 2nd Edition, by Steve Krug
• Letting Go of the Words: Writing Web Content that Works, by Janice (Ginny) Redish
• Writing for the Web research from the Nielson Norman Group

Adapted and expanded from Letting Go of the Words by Janice Redish and Hampshire College's Web Writing Style Guide