Planning and Writing Your Documents

Chapter 6 Barker
Katy Mears and Erik Sorensen

There are nine phases in the documentation process. They are:
1. Start the project
2. Perform the user analysis
3. Design the documents
4. Plan the documentation project
5. Write the Alpha Draft
6. Conduct Reviews and Tests
7. Revise and Edit
8. Write a Final Draft
9. Conduct a Field Evaluation

This chapter also summarizes development of online help systems. Each guideline includes an examples and project plans.

1. Start the project
-Get to know to software you are writing about
-Remember that a good manual is based on the user, not the software
-Writers will most likely work in teams. There are two kinds of teams: development teams and writing teams. Development teams have members who deal with the programming, planning, and marketing of the product. Writing teams members write, edit, and test documents (175).

The Development Team (176):
-Develops entire product—both software and documentation
-Persons on team include product developer (designs program, considered expert on subject), project manager (organizes project and keeps members on track), market/systems analyst (studies users and activities that the documentation will describe), technical specialist/programmer (writes and tests the program), and documentation specialist (handles writing of manuals and help programs).

The Writing Team (176):
-Develops documents for program
-Not always “clear distinctions” between roles
-Persons on team include manager (in charge of overall project, keeping members on task, and maintaining documentation plan), lead writer (does user analysis and writes drafts of documents and topics), writer (creates content), editor (edits documents and sets up consistency standards), graphics designer (handles artwork and screen captures), and tester (maintains documentation quality by testing the documents).

Preliminary research is a part of starting the project. There may be documents developed by the members of the developing team about the software. These documents include project plans (identify goals and justification for the software and may also include what problem the software intends to solve), program specifications (instructions on structure of program and what operations need documentation), market analysis (sales research on software buyer—not to be confused with user, who needs to be able to understand the documentation), information plan (the documents needed by users), and management plan (resources, people, and schedule for completing the project). The information plan is most valuable to the writing team because it is focused on the user’s needs (178).

Online Help Development Process (179-184):
An online help system is in WinHelp or HTML format. It is arranged around user’s workplace activities and contains different types of documents about the program. This format can contain more clever and helpful ways of presenting information because of technological advances. The stages of development are similar to the nine stages in documentation. However, user analysis focuses primarily on workplace activities and the user’s software skills. The time management schedule will vary to prepare for “inevitable delays” that can occur in developing the program. Testing the help system is also more complex because of hyperlink testing and troubleshooting. Writers also need to test in different environments because the program will be used in a variety of “computer platforms (Windows, Macintosh, Linux, etc).”

The first decision the writer needs to make when starting a help project is to determine what “authoring environment” (software program that you will use to write help documents). Different programs have different features. A usable program should have single-source capabilities, authoring features, and management features.

2. Perform User Analysis (184)
-Research what makes the software effective by interviewing and observing the users
-Develop a table of contents based on these tasks
-Default Manual: a manual that “records the functions of menu items, commands, and dialog boxes, but doesn’t structure the information according to user tasks (185)”

3. Design the Documents (187)
-Apply the three types of documents (tutorials, procedures, and reference) to the user
-Outline documents and determine layout

4. Plan the Documentation Project (189)
-Write a project plan for deadlines and to clarify each member’s responsibilities
-Design plan: plan for document design
-Documentation plan: specify manuals and outline help if needed. This will be the main document in organization
-Project plan: plans for further research and other design work. Project plans include information about meetings, deadlines, project report deadlines, test completion notes, review deadlines, and edits. It should also include estimates for document length and the amount of time it will take to complete it. It should also list the resources to use to complete the project such as human and material resources. Human resources are the efforts of the sponsors, users, testers, reviewers, and editors and their time should be planned for accordingly. Material resources include the computers and equipment on the project. Writers should be familiar with the technology they will be using.
Assign People to Tasks
-Determine roles of team members
Editor-writer-tester-graphics designer-review coordinator
-Keep in mind the talents of your staff, assign people to their strengths
-Writing skills
-Editing skills
-Software tool skills
-Subject matter expertise
-Familiarity with environment

Calculate Time/Page and Screen Estimates
Sometimes it’s easier to use a formula to estimate the time and length your documentation will be. There are some things to keep in mind:
· Type of documentation – Tutorial, procedures or reference document you may need to add information. Tutorials take more space because of listing explanations conversely documentation requires only the bones and takes less space
· Availability of information – If information about the documentation is not readily available you may need to add time
· Experience of writers- Writers with more experience can do more work in less time. The more experienced the writer, the faster the product can be completed
· Reliability of the program-If your program is being tested while you’re working on it then it may take longer to complete because you will be revising it as you go

Write the Help Project Plan
Some documentation requires both online help and print help topics. In this case your documentation plan will reflect both. In the Sevensteps authoring environment the program is designed to work with four people: Project Leader, Author, Domain Expert and Developer. The estimator will use formulas to calculate how much time each person working on the project needs in order to complete a given number of tasks.

Reviewing the Documentation Plan
The documentation plan will go through a thorough review by managers, clients and users. The documentation plan gives you the opportunity to hold a user walkthrough and a technical walkthrough.

#5 Write the Alpha Draft
The alpha draft represents your first complete document including all the front matter, text, graphics, appendixes, indexes and associated documentation set materials. Follow style guidelines and it is a good idea to create an alpha checklist. It may be a good idea to because this will show other writers what has been done,



Draft the Help Topics
Writing help topics requires that you not only supply content for each topic, but supply information about the topic that the system uses to relate it to other topics. Writing of topics involves creating content, but also creating important links and interconnected relationships among topics and recording them using the help authoring system. Once the topics are written a special program call a help compiler is needed to read the topic. Often you will encounter errors in creating help topics such as unrelated or cross related topics.

#6 Conduct Reviews and Tests
Because the alpha draft contains all the elements of your product, you can send it out for review by clients, executives, and managers, as well as users. You can also design usability tests using the original documentation objectives, to test for elements such as accuracy, task orientation and so on.

Conducting Reviews and Tests of Online Help
Testing occurs after the compiler has successfully created a version of the help system that you can circulate among users and clients Testing will occur often and therefore it is important to separate and schedule testing of the technical elements and content accuracy.

#7 Revise and Edit
You can often revise and edit your own work then submit any changes to the editor or just simply continue editing your own work. This will allow checking for accuracy on many levels.

#8 Write a Final Draft
Writing a good final draft should be accomplished a lot easier if you have done a good job in the previous stages

#9 Conduct a Field Evaluation
This is the last stage of evaluation. From this stage you can analyze and gauge how well your document and help system met the needs of the user. You can provide the user with feedback links in HTML format or simply give them email links in order to provide you with the necessary feedback for your product.

Chapter 6 Campbell: How Do I Get Them to Read This?

Larson/Tradup

First impressions count!

Set the Stage
Investigate if internal communication is effective and be prepared to explain why your new document is a better plan.

Hooking your audience
Remember rule: appearances count

• 70% of what you know is based on appearance
• your reader assess simplicity, form, clarity, shape, color, highlights, density, sharpness, and contrast at a single glance
• they want to know if your document is worth their time
• they don't want chaotic, crowded, noisy documents

Use the hidden documents design to:

1. get readers in the door
2. encourage them to stay and read

Create Visual Appeal

Hidden power of document design is what it does for the appearance of your document. Remember the Madison Avenue lesson: "If it looks organized, uncrowded, and easy, it must really be."

Avoid Visual Clutter

Visual clutter is the result of a document that looks overwhelming; "that stuff in the garage." Two things are required for an easy-to-read and look at document:

1. simplicity
2. clarity

Designing for Visual Appeal

How can the clutter be controlled? By using basic design elements to make the document look easy, fast, and clear, i.e. visual appeal:

20 basic design elements

sentence length, paragraph length, line spacing, typestyle, typeface, emphasis, paragraph spacing, justification, indentation, margins, headings, graphics, visual weight, contrast, color, symbols, columns, lists, forms, white space

Why do design elements work?

1. the human brain

-can deal with as many as seven different items at one time

-can clearly distinguish among only three of the seven items at one time

Solution: use the Rule of Three

2. eye movement

-takes in about forty characters at once

Solution: consider using columns, break information into chunks

-takes in three or more words/second

Solution: use headings, sections, concise wording to make message obvious

-reads two or more words at one time

Solution: reinforce unimportant words that carry critical meaning; avoid excessive adjectives, descriptors, fancy phrases, complicated clauses

-moves top to bottom, left to right in a Z pattern

Chunking as a visual technique

• present information in small, simple chunks that are well organized
• white space: the more white space, the faster the document is read

Consistency is all

Help readers develop a rhythm for comfortable reading