1. Panayiotis Christodoulou
USERS SUPPORT
Panayiotis Christodoulou

2. Previous Lecture Goals of training activities
Steps in the training process
How to plan a training session
How to prepare a training session
How to present a training module
How to progress toward quality training

3. Writing for End Users The types of end-user documentation
How technical writing differs from other writing
How technical documents are organized
How to plan effective documentation
The technical writing process
Effective use of formats
Strategies for technical writing
Common problems in technical writing
Tools used for technical writing
How to evaluate documentation

4. Notes
The creation of any documentation aimed at end users regardless of the format requires a basic knowledge of technical writing. Documentation is any form of written communication intended to provide user support information to end users. When documentation is well written it can save users time and can help increase productivity

5. Types of User Documentation
User documentation can take a number of different forms. Brochures and flyers often promote various compute rrelated activities, such as staff training sessions, open houses, computer fairs, hardware and software product demonstrations, and guest speakers. Newsletters are an important way that support groups communicate with users.
Handouts and training aids are primarily intended to summarize and promote recall of material covered in a training session. User guides, handbooks, and computer manuals are more formal examples of written documentation. These manuals may be organized into a tutorial format, which guides a user step by step through the features of a program while other manuals may be organized into a reference format, where all the information on a specific topic is located in one place.

6. Online help systems and software assistants (wizards) are increasingly common in software packages. Even though online documentation is convenient, some users still prefer to read large amounts of information in printed form. Many support organizations have switched their primary method of support from telephone to e- mail and instant messaging (chat), which requires support specialists to write well. Because an increasing amount of written materials end up on the World Wide Web, the ability to write for this medium is an important skill. Support specialists also need to be able to write proposals, letters, and memos.

7. Support specialists are often called upon to write procedural and operational documentation that includes such things as the descriptions of the steps to install hardware and software. User support staff members are also often called upon to write troubleshooting guides to help other employees solve support problems.

8. How Technical Writing Differs from Other Writing
Technical writing follows particular style guidelines. Generally, in technical writing, the author uses short declarative statements rather than long complex sentences. The most important points are stated at the beginning. Often, technical writing contains step-by-step sequences of events or tasks. The writing should be concise but not cryptic. To add more detailed information, the support specialist can add pointers, or cross-references to the location where more information can be found. Also, the author should not try to entertain readers with humor or call attention to the writer’s personality or preferences.

9. Two common ways to organize technical documents are sequential and hierarchical. Sequential organization follows a step-by-step approach where information is arranged in order from first to last. Hierarchical organization flows from top to bottom and information is arranged from general to specific.
Many successful technical documents use a combination of sequential and hierarchical organization. There are generally three parts to a technical document. The introduction explains the purpose of the document, who should read it and why someone would want to read it. The body has a general explanation, specific task steps and common problems users encounter. The last section is a summary section that provides a concise overview and points to additional information.

10. Documentation Planning
The steps that are taken when planning a document are very similar to those taken by trainers planning a training session. Identifying the target audience can guide how task descriptions are written and at what reading level the author should target the writing. The author should determine what the assumptions he or she has about what the audience already knows and write a short statement in the introduction so that readers can make an informed decision about how much help the material would be for them. It is also important to determine what the audience needs to know once they finish the document. The writer should also have a clear idea of what they would like the audience to be able to perform after they finish reading the document. Finally, the writer should understand the medium that will be used to communicate the document in advance. For example, if the document is going to be formatted as hypertext, the author can take advantage of hyperlinks to point readers to other sources of help and information.

11. The Technical Writing Process
Step one is to generate a list of ideas. At this stage, a writer brainstorms to generate as many topics as they can think of that might be useful to readers. Step two is to organize the list into an outline. Step three involves expanding the outline into a first draft. This can include creating paragraphs with topic sentences. Using transitional words such as “for example,” “therefore,” and “as a result” to help readers find the relationship of one sentence to another. It is important to define new terms. Also, consistent formatting features can help readers to understand the organization of information more easily. Style elements such as different fonts, font sizes, boldface, capitalization, centering, indention, underlines, bullets, and numbering help a reader to understand the structure. Formatting consistency is important. Finally, lists and tables are often more understandable for users compared to long narrative passages.

12. In step four, writers read and edit the draft
In step four, writers read and edit the draft. The first edit pass is often used to delete extra words and tighten up the prose. A second editing pass is to perform a format consistency check to make sure that the font of headings and subheadings, indention, centering, boldface, italics, and underlining are used the same way throughout the document. A third edit pass is a technical accuracy check where a writer performs any procedural or technical steps in a document to test them with the hardware and software.

13. Step five is to have an outside review of the draft
Step five is to have an outside review of the draft. It is important to have another expert identify problems and raise questions about the work. Once the writer receives feedback from step five, he or she moves on to step six of revising the draft. The hardest part is to know when to stop editing. After each editing pass, a writer should review the changes made in the last pass and determine if major improvements are still being made or if the changes are marginal. If the last pass generated no significant changes to enhance the readability and accuracy of the document it is time to stop. Step seven is proofreading the document. Proofreaders look for a variety of common errors including inconsistent capitalization and punctuation, inconsistent font use, extra spaces between words and sentences and incorrect page breaks.

14. Technical Writing Strategies
Technical writers often use analogies to explain new material. An analogy describes how an unfamiliar concept is similar to a familiar concept. Repetition can be used for emphasis. Technical writers try to use words consistently so that readers do not become confused between the subtle meanings of words. Many documentation departments and organizations maintain a style sheet that lists their preferences for common terms so that all writers use the same terminology. It is also important for technical writers to use consistent verb tense.
The concept of parallel structure is important in technical writing. Parallel structure means that similar items are handled consistently throughout a document.

15. Common Problems in Technical Writing
One of the most common mistakes is the over-use of design elements. Desktop publishing and word processing software programs are readily available and their ease of use often leads novice writers to overuse design tools available. A writer should use considerable white space where readers can rest their eyes. Body copy should not be any smaller than 9 point. It is better to edit content to be more concise rather than making the copy smaller to fit on a page. Avoid centering text or justifying (sometimes called block justifying) text as it makes the copy very difficult to read. Leftaligned text is the best option in most cases.
For most readers, serif typefaces are easier to read than sans serif. Serif typefaces include serifs, fine lines that project from the top and bottom of a font’s letter. Sans serif typefaces do not have the serifs. Specialty typefaces such as script fonts should be saved for informal use.

16. It is important to be very careful with gender references
It is important to be very careful with gender references. In recent years pronouns such as he, she, him and her have been replaced with gender-neutral words such as they, their and it. Phrases like “he and she” or “she and he” are acceptable ways to avoid gender specific language in general references.
Another common problem in technical writing is the use of unclear referents. A referent is a word that refers to another word or concept. Avoid passive voice which is a grammatical structure that uses a form of the verb “to be” and the –ed form of the verb.

17. Avoid nominalization which is the process of creating a noun from a verb or adjective. In general verbs are easier to understand. Another problem is wordiness that can lead to long sentences and hinder understanding. Jargon, which are words understood only by those experienced in the field can be confusing. Like jargon, acronyms, or a series of letters that represent a phrase, can make technical writing difficult to understand. A dangling phrase is a few words (or a single word) at the beginning or end of a sentence that add little to the meaning of the sentence. It server only to make the sentence longer and can be distracting to the reader.

18. Technical Writing Tools
Many word processors include tools that can help support staff to develop useful user documentation including an outliner to help organize work and a spell checker to identify and correct spelling errors. A custom dictionary can be used to contain jargon words and acronyms. A thesaurus can be used to help find a word that exactly expresses a concept. Other tools include a grammar checker to recommend changes in wording to improve readability, a readability index to indicate the level of difficulty for the audience and desktop publishing features to help writers produce documents that appear more professional.

19. Documentation Evaluation Criteria
All technical writers have personal preferences and writing styles. The ultimate measure of user documentation is how effectively and efficiently information is communicated to the readers. For technical writers, effectively means readers get the correct information they need to master a topic or perform a task. Efficiently means readers do not have to spend extra time searching for information or reading through irrelevant material to find what they need

20. There are four general criteria that can be used as an evaluation checklist. For content, the document should be evaluated for accuracy and completeness of coverage on the topic. The organization of the document should make the information easy to locate. There should be clearly identifiable transitions between topics, and the user should be able to get in and out quickly with the correct answer. The format should be consistent and have a layout that helps guide the reader. Finally, the mechanics such as correct spelling, grammar and effective writing style should be evaluated.
Regardless of a document’s intended use, the purpose remains the same: clear communication that addresses readers’ needs by giving them concise information they can use.