Text is Not an Ugly Step-Sister! What Web Writers Can Learn From Technical Communicators

Note: This article was inspired by, and has borrowed liberally from, Duncan Kent's Writing Revisable Manuals: A Handbook for Business & Government. I've frequently referred to this excellent resource over the years—ever since Duncan assigned it as required reading for one of my first tech-writing classes. It's fantastic to know that, in this era of ever-changing technology, basic principals continue to remain true. Thanks, Duncan!
____________________________________________________

It's no secret that there's more than one way to present information online. In fact, there's a dizzying array of ways. But this article isn't going to address videos, podcasts, presentations, infographics, or any of the other sexy communication methods that are important to engage and entertain your audience. Because text-based web pages still makes up a large part of the communications online, and will for many years to come. And most text-based web pages still really suck.

One reason why web content continues to suck is because most of the discussion about presentation methods take us away from text. Text is treated like an ugly step-sister we have to deal with, while we give all of our attention to the prince charming of social media and creative communications. But, text is not an ugly step-sister! It's the foundation of most online communication strategies, and it's way past time that we integrated better presentation methods within our text-based web pages.

After all, technical communicators have been all over this for years. There's a few tricks we could borrow from them. Here's a few "Tech-Writing 101" presentation tips that every web writer should master.

Narrative text
Narrative text is best for telling a story. It's also useful as introductory text before other presentation methods. When you use narrative text by itself on a web page, for a story or article, break it up with multiple sub-headings and consider adding sidebar text to highlight certain elements. Try to avoid using only narrative text on product or service pages.

Bullet Lists
Bullet lists are not the silver bullet of web writing that they're often made out to be. I can't tell you how many web-writing guidelines I've read that tell people to break narrative text into bullet lists without any more guidance than that. In my opinion, that's a crime. But bullet points are very useful if you follow some basic rules:

• Use bullet lists for three or more related items.
• Structure all items within a list similarly (for example, if one item begins with a verb, they all should).
• End complete sentences with a period. If any item on a list is punctuated, punctuate every item.
• Do not use numbers unless the sequence of the items is important. Bullets imply random order.
  

Checklists
Checklists are simply lists that have tick boxes in front of each item. Use them when you want to help readers ensure they have all of the proper materials or have completed all required tasks. If you use a checklist, provide and easy and obvious way for readers to print the page so they can actually use the checklist.

Sidebar text
Sidebar text is used to call out information that is related to the text on the page. If you use sidebar text, make sure that its design immediately differentiates it from the body text on the page. Some examples of when you may want to consider using sidebar text include:

• To provide commentary on the text.
• To emphasize key concepts.
• To provide definitions of technical terms.
• To highlight quotations.
• To provide tips.
• To provide supporting information.
• To show a short example of the key concept at work.

Tables
If you have to convey a large amount of data, using a table is often the best way to do it. Tables are also useful to compare different products in terms of characteristics such as size, weight, price, or performance. "If... Then" tables are excellent when you want to show different conditions. Here's some tips for writing tables:

• Introduce the table in the text preceding it. Don't expect readers to figure it out entirely for themselves.
• Simplify the table data down to just that amount of data that illustrates your point (without distorting the data!).
• Don't put the unit of measurement in every cell of a column. For example, in a column of measurements all in millimeters, don't put "mm" after every number. Put the abbreviation in parentheses in the column or row heading.
• When there is a special point you need to make about one or more of the items in the table, use a footnote instead of clogging up the table with the information.

Charts and graphs
Charts and graphs are actually just another way of presenting the same data that is presented in tables — but a more dramatic and interesting one. However, they provide less detail than tables. Imagine the difference between a table of sales figures for a ten-year period and a graph for that same data. You get a better sense of the overall trend in the graph but not the precise dollar amount.

Step-by-step procedures
Use step-by-step procedures to describe tasks that the reader must carry out in a specific order. Don't bury procedures in narrative form. Use step-by-step when there is a consistent linear pattern without a lot of decisions to make. If there are a lot of decisions required, consider using a decision tree instead. Here are some guidelines for writing step-by-step procedures:

• Use the imperative style, beginning each step with an action verb (for example, “Calculate the amount of tax payable….”).
  
• If the step is conditional upon something else, state the condition first (for example, “If you have expenses, complete the Expense Form and attach your receipts.”).
  
• Order steps in the sequence in which they must be carried out.
  
• Number each step. Don’t include more than one activity in a step.
  

Playscript procedures
Playscript is a simple variation of step-by-step procedures used where several people are involved. It specifies which person is responsible for each step by including the name or role in front of a numbered when the person responsible for that step changes.

Flow diagrams
Use a flow diagram to provide a graphic overview of the relationship between things, how processes work, or how documents move. Don’t try to illustrate every step in a complex procedure—this is better left to step-by-step procedures. Flow diagrams are also good for showing feedback loops and branches within procedures. Here are some tips on creating flow diagrams:

• Keep the number of shapes to a minimum. Stick with the standard shapes, and always include a legend explaining the meaning of each shape.
  
• Indicate the start point.
  
• Don’t cram a lot of text into the shapes—the purpose is to provide a graphic overview, not to give readers all the details

Decision trees
Decision trees are a form of flow diagram in which readers are routed according to their responses to questions. Use decision trees to provide a visual representation of conditional steps in a procedure, or to help readers decide which procedure to use. Each box of the decision tree can indicate a different procedure.
Here are some tips on creating decision trees:

• Use diamonds for questions and boxes for actions.
  
• Always indicate where the reader should start.
  
• Try to keep the text in the shapes to four or five words.
  
• Keep the shapes the same size.
  
• Don’t include more than one action in a box. If necessary, refer the reader to a step-by-step procedure.

 
Still not sure which presentation method you should choose? Check out Duncan's table of content presentation methods.

Did I forget any major content presentation methods for text-based web pages? If so, let me know in the comments!