PRDV002: Professional Writing

What is Good Web Writing?

• Writing is like having a written 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 are not 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 will 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.
  
  
• Allows people to grab and go. Breaking information into pieces for different users, topics, and needs helps readers grab what they need, move on to their next question, complete their next task, make a decision, or whatever comes next.

Web writing is more informal than other formats. You should aim for a voice that is clear, credible, trustworthy, and welcoming.

Focus on Essential Messages

Give Each Page a Clear and Descriptive Title

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

Do Not Waste Space Welcoming People to the Page

There is no need for any welcome text as a filler. Most users ignore it.

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 the inverted pyramid style to the traditional narrative style.

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 your company, use plural pronouns: "we" and "us."
  
  
• Define unfamiliar terms, especially for those outside your company. Do not 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 coworkers does not 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.
  
  
• 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 cases.
  
  
• Do not 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. Do not 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.

• 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 on 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.
  
  

Make Content Accessible

Good web writing and design make 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 and More here!
  
  
• 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 is left."
  
  
• As much as time allows: read your work out loud, let the writing sit for a couple of days and return to it, or ask a colleague for edits.
  
  
• 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 your company. 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 do not forget. Give yourself the time necessary to update your content.

---

Source: Duke University Libraries, https://library.duke.edu/about/writing-styleguide
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 License.