Electronic Documents Should Be

Electronic documents should be...

Better-written technical documents enable people to work with greater speed, accuracy, and comfort. These qualities

1. short,

are measured by the usability factor.

2. top-heavy,

Sun Microsystems researchers applied several simple

3. scannable,

writing strategies to test web pages, improving the usability

4. navigable, and

of a tourism web site by 127%, and a technical web site

5. straightforward.

by 149%. (See "Web Usability Studies").

Note: These strategies are designed to improve informational web pages, but some nontechnical web sites also have value. The Internet has room for writing that creates suspense,

style,

and

poetry.

1. Electronic Documents Should Be Short The shorter, the better. 2. Electronic Documents Should Be Top-heavy The inverted pyramid writing style puts the important information at the top. People do judge books by their cover; and they will judge web pages by what they can see without scrolling. •

If your first few lines satisfy your reader's needs, you will have

done your job well. •

Curious or skeptical readers can keep reading, perhaps following

links deeper into your document. •

Bored or satisfied readers can move on.

Use the inverted pyramid on several levels, whether you are writing a paragraph, a single page, or a multi-page collection.

•

Paragraph o

Begin with the conclusion. (It may be all your visitor

has time to read.) o

Use subsequent sentences to support your conclusion.

o

Use bulleted lists and highlighted keywords to break

up long, boring blocks of text. •

Page o

Begin each page (or posting) with a table of contents, or

a detailed abstract. o

The abstract should provide the Coles Notes version of

your page: "This web page has some neat links and



cool

graphics."

(Vague and completely useless.) "This web page offers links to my favorite



science fiction TV shows and some original computer graphics." (Although slightly improved, this version still lacks any specific details.) "This web page has an annotated list of



links to Canadian Star Trek and Babylon 5 web sites, and graphics that emulate their computer interfaces." 

(This more informative summary helps the

reader evaluate a document without reading it to the end.) •

Collection o

Provide an informative overview, near the top of the

first page (in order to minimize scrolling). o

Different kinds of electronic documents require slightly

different overviews. For example: 

A web home page should contain: 

a statement of purpose



a table of contents



An on-line manual, help file, or FAQ (list of

"Frequently Asked Questions") should contain: 

a condensed, easily-accessible index or

table of contents for those who want a quick overview 

items

arranged

so

that

the

most

common problems are the most easily solved. 

An archive or list of links should begin with: 

a clear description of the selection

criteria 

a summary of contents (the better the

summary, the more useful the collection) 3. Electronic Documents Should Be Scannable

Conventional Text

Scannable Revision

Traditional writing genres, such as the five-

Electronic Documents Should Be Scannable

paragraph essay, or a short story, are usually harder to read on a visually-intensive electronic

People dislike reading long paragraphs of

media such as the World Wide Web, because

electronic text. Technical paragraphs are often

computer users dislike reading long paragraphs.

inefficient

On average, people read electronic 25% slower

information, and electronic text is harder to

than

read.

conventional

text.

Monitors

cause

eyestrain, it takes time for long pages to download, and it is easy to lose your place in an electronic document. Traditional writing modes such as essays and narratives use long blocks of

ways

of

conveying

complex

Users prefer scannable text, so that they can glance over a page and quickly gauge its value. Scannable text uses

text in order to build gradually and inevitably to

•

descriptive subheadings,

a conclusion. This kind of writing assumes a

•

highlighted keywords, and

captive audience -- readers who want to absorb

•

bulleted lists.

every word and idea on the page, in the order that the author presents them. Technical authors cannot make the same assumptions, because

Technical Paragraphs Are Often Inefficient

time is money in the professional world, which means that people will bail out of what looks

More traditional writing genres, such as the

like a boring document, unless they see concrete

five-paragraph essay or the short story, build

signs of useful information. Documents which

gradually and inevitably to a conclusion.

emphasize their most important information

Long paragraphs are acceptable in this kind of

with

writing, because the reader is expected to read

meaningful

subheadings,

highlighted

keywords, and bulleted lists allow readers to scan the document -- to glance over its contents quickly, stopping whenever they encounter something interesting, and skimming ahead when they are bored. People "who surf the 'net" will likely try to surf your document as well, which means that long blocks of plain text will appear to be more trouble than they are worth. The first person who actually reads this far in

every word, in strict sequential order. Technical readers want the conclusion up front. They will bail out quickly, unless they find something interesting. They will scan ahead

in

order

to

predict

a

page's

usefulness, focusing on the words and phrases that jump out at them. Electronic Text Is Harder to Read

the text should e-mail the author to receive a free, autographed picture of the cast from "Full

•

read.

House." Preparing and revising electronic documents according to this principle is a time

•

Many users report eye strain or other discomfort.

consuming project which, judging by the prevalence of text-heavy web sites on the

Electronic text takes 25% longer to

•

Users lose their place when pages are densely packed.

Internet, many people do not want to do; however, the time that you have already invested in doing the work in the first place is

•

Blocks of text can be intimidating.

completely wasted if your users never find it on your site. Analysis Although the paragraph on the left actually contains more information, not all of it would be of interest to the users who come to this page, and there is nothing that would particularly attract the attention of those who might be interested.

The revision on the right highlights the most important details; an author can use hyperlinks to send the reader to related subdocuments or to lower sections of the same

page

in

order

to

provide

more

details.

4. Electronic Documents Should Be Navigable Non-expert users typically depend more heavily on help files, navigation aids, and other supporting features. As more ordinary people encounter electronic media, those elements become more important. As an electronic author, you should generally help a novice use your document. At the same time, too much help slows down the experts. •

•

Use hyperlinks with care. o

Build links using informative text.

o

Avoid extraneous links.

Expect late arrivals and premature departures. o

Any page on your site may be the only page your

reader sees. o

Help your reader navigate efficiently.

Use Hyperlinks With Care In some ways, hypertext frees readers by letting them pick and choose from among several paths through a document At the same time, hypertext restricts readers, because they can follow only the links the author chose to create. As an electronic author, you should build links using informative text, and avoid extraneous links. •

Build links using informative text

Take advantage of the fact that linked text stands out, and use it to highlight the important information you offer. Use the surrounding words to explain why the reader might want to click on the link.

For a web page about plagiarism, click here.

o

(Sloppy writing; the word "here" jumps out, but it means little by itself.) Click on the following link for a web page about

o

plagiarism. (The linked text is more descriptive, but the sentence still offers no good reason for a reader to follow the link; further, since most readers don't need to be told that you click on links to make hypertext work, the instruction wastes time.) All students are required to know the university's

o

official

definition

of

plagiarism.

(The linked words describe what the document is about, and the context clarifies why a reader might want to read it.) •

Avoid extraneous links o

For a reader with a specific goal in mind, link-saturated

paragraphs

can

be

distracting.

My name is Dennis G. Jerz. At present, I work for the Engineering Writing Centre in the Faculty of Applied Science and Engineering at the University of Toronto. I am completing my Ph.D. at the Graduate School of English. I am a citizen of the United States of America, although I have been living in Toronto, Ontario, Canada for six years. I received my B.A. and M.A. in English at the University of Virginia. I have recently accepted a job in the Department of English at the University of Wisconsin-Eau Claire. (Many people's first web pages include passages like this. It may be fine for beginners who simply want to play with hyperlinks, but an annotated list is a much more efficient and useful way to organize a series of links.) o

Internal cross-links may fight each other for your

reader's attention. o

Links to external sites may send your reader away

prematurely.

Obviously the solution is not to hide links; rather, offer links that actually help a reader who wants to use your resources to achieve a goal. Expect Late Arrivals and Premature Departures Any page on your site may be the only page your reader sees. Make it as useful as possible. •

Even a Brief Visit Should be Productive o

On the way in... 

Search engines may point users directly to one

of your internal pages. 

Don't assume your visitor has read any of your

other pages.  o

Treat each page as an independent document.

On the way out... 

Users can and will leave your web site. A technical or service-oriented web site



should try to satisfy the user as soon as possible. Do not try to trick them into staying



longer. Aim to send them away satisfied.

 

If you want to keep their interest longer, don't

employ tricks -- write stuff that's more interesting. •

Orient Your Reader Within Each Page o

Provide meaningful navigation aids. 

[

Go

Back

]

(This link would mean nothing to a user who didn't come from the place you want to send them.) 

[

Home

(There are millions of home pages out there.)

]



(While most users of the present web site would probably understand the function of this graphic, to novices, it may seem like just a pretty picture. [Hint: click on it.]) [ Engineering Writing Centre Home ]



(Low-tech, but more informative than the graphic. [So: why does this site use the logo instead? Well... umm... you see, graphics are cool...]) o

Provide navigation alternatives. 

Is your document sequential, with a clear

beginning and ending? That may be good, and it may be bad. 

Novice

users

typically

prefer

a

sequential document, so they can tell when they have finished. 

Expert users may object to tedious

strings of "Go to next page" links. 

A user should be able to change navigation

strategies from moment to moment 

The main navigation bar at the top of

this page clearly reflects a hierarchical arrangement. 

The arrow buttons at the top and

bottom indicate the sequential arrangement of documents in this particular section. 

The arrows appear at the top of

the page for those users who want to click quickly through all the pages, in order to get an idea of what each page contains. 

The arrows also appear at the

bottom of the page because that's

where sequential readers will end up when they make their decision about whether they want to keep reading. 

the

The occasional hyperlink embedded in main

text

indicates

a

thematic

arrangement among various sections Electronic Documents Should Be Straightforward •

Avoid "marketese" o

Click here to see the best web site ever! You

won't

be

sorry!

(Users detest this kind of writing. They end up mistrusting the web page, even feeling insulted by the writer.) •

Avoid pompous and overblown language.

Pompous

Straightforward

At this point in time...

Now...

Due to the fact that...

Because...

It is important to note that...

[cut entirely]

From X, it can be seen that Y is the case.

X proves Y.

•

Don't hide behind words. Say what you mean. o

At this point, the management would like to offer

its most sincere sympathies for any inconvenience that might have been caused by the recent, brief network incident. Our valuable customers should rest assured that we remain committed to offering reliability and affordability blah blah blah... (If this is supposed to make amends to customers who have suffered a great inconvenience, it is a sorry attempt.)

o

We regret the inconvenience caused by the server

crash -- we hate being locked out of the network just as much as you do. The upgrade should be completed by Monday morning. (The informality and directness of this passage is more believable -- a reader would tend to believe that this writer actually did feel bad about the "incident.")