1

Technical & Business Writing (ENG-315)

Muhammad Bilal BashirUIIT, Rawalpindi

Outline

1. Guidelines for Planning a Documentation Project4. Plan the Documentation Project

5. Write the Alpha Draft

6. Conduct Reviews and Tests

7. Revise and Edit

8. Write the Final Draft

9. Conduct a Field Evaluation

2. Summary

2

Planning and Writing Your Documents

Lecture: 16

3

4. Plan the Documentation Project A project plan for your document is required to manage

a project, so u need to know how to write a project plan The writers and other team members will need this

plan as guidepost for their activities This plan can be taken as deadlines and to clarify their

responsibilities, to identify knowledge resource they have, and so on

As a member of the team, you need to know about the plan from the manager’s point of view So you can understand and respect the kind of work the

manager put into it

4

Plan the Documentation Project (Continue…) List Project Events

Documentation project involved series of events called project tasks that allows you to manage the effort it takes to write a software manual or help system

After listing together, share it with the other people in the project and get their approval and input

What Goes in the Project Plan Schedule of events for completion of your project Plans for using resources Time/Page estimates

5

Plan the Documentation Project (Continue…) Decide What to Schedule

Meetings Deadlines for drafts Project report due dates

Test completion Review deadline Edits

6

Event Start Date End Date Personnel

Complete user analysis

15/4/2012 1/5/2012 Manager, writer, user group

Progress Report 15/5/ 2012 Manager

Write draft 21/6/2012 7/7/2012 Writer

Editing 9/8/2012 25/8/2012 Writer, editor

Plan the Documentation Project (Continue…) Types of meetings associated with Documentation

Process Regularly Scheduled Meetings: To check progress,

problems faced during development Special Meetings: Occur at project milestones

7

Types Attendance Purpose

Review Meeting All persons who review a draft

Go over the review information and resolve conflicts

User Walkthroughs

Selected users Go over the documentation design plan for suitability, ease of use and usability

Technical Walkthroughs

Programmer Go over the program task list for inaccuracies, omission and logics

Plan the Documentation Project (Continue…) Kinds of reports associated with the documentation

process

8

Report Writer Reader Description

Evaluation Team leader Supervisor/ Sponsor

Describe and evaluate work of team member

Progress Writer/ Team leader

Manager/ Client

Describe work to date and plan for completion

Test Writer/ Tester

Manager/ Writer

Describe the results of tests and recommends revision

Oral Briefing

Writer/ Team leader

Manager/ Development team

Present new tasks, review progress, discuss team business

Plan the Documentation Project (Continue…) Estimate how long

the project will take? Plan human and

material resources

9

User’s Guides

Phases %

1. Start the project 8

2. Perform the user analysis 15

3. Write the project plan 15

4. Design the document 8

5. Write the alpha draft 15

6. Conduct reviews and test 15

7. Revise and edit 8

8. Write the final draft 8

9. Conduct a field evaluation 8

Total 100

Plan the Documentation Project (Continue…) Assign People to Tasks

The documentation team manager determines the roles team members will play

As manager you know the talent and experience of your team members

When assigning the tasks, keep in mind the following characteristics Writing skills Editing skills Software tool skills Experience with the subject matter of the program Knowledge of the user and user’s workplace Familiarity with the development environment

10

Plan the Documentation Project (Continue…) Calculate Time/Page and Screen Estimates

You can roughly calculate the number of pages and screen in a document using formula depending on the user activities you plan to support

The estimation starts with your table of contents where you can see list of operations you have to describe for users

You can roughly estimate number of pages in your final documentation by calculating number of overall program operations multiplied by the average page length

Multiply the grand total of all pages by the industry standard of 2.9 hours per page to find out number of hours you will require to produce complete documentation set

11

Plan the Documentation Project (Continue…)

12

Activity: creating a basic calendar

Operation Needed

Page length Screen shots

TotalLong = 1Med = .5Short = .25

Include = .5Spot graphics = .25Not needed = 0

Creating a Calendar 1 .5 1.5

Importing an Image 1 .5 1.5

Changing the Typeface .5 .5 1

Insert text on Date .5 .25 .75

Printing a Calendar 1 .5 1.5

Saving a Untitled Calendar .5 0 .5

Total Pages 6.75

Total Hours 19.575

Plan the Documentation Project (Continue…) The total page count can be different depending few

other parameters Type of documentation

2.9 hours is for procedures, Tutorial takes 50% more and Reference documentation takes 50% less than that

Availability of information How much time it takes to get the required information

Experience of writers Experienced writers will produce the contents quickly

Reliability of the program If the program is not well tested or going through testing, there is a

chance that procedures will have to be changed once a bug is fixed or a new feature is added

13

5. Write the Alpha Draft

It represents first complete document, including all the front matter, text, graphics, appendixes, indexes and associated documentation set materials

As a written document, the alpha draft is tested, reviewed and edited-all according to the specifications laid out in the documentation plan

Writing topics is a matter of either writing new content using the authoring environment of a help system, or importing content from files that you will also use in a print document

14

6. Conduct Reviews and Tests As your alpha draft contains all the elements of your

product, you can send it out for reviews by clients, executives and manager as well as users

At the same time, you can design usability test using the original documentation objectives, to test for elements such as accuracy, task orientation etc.

Information from reviews and tests provides feedback for the next draft to set

Testing the system occurs after the compiler has successfully created a version of the help system that you can circulate among users and clients

15

7. Revise and Edit

While reviews and tests provide feedback, this phase allows you to submit your work to an editor or to edit your own document

Revising and editing of a help system means that you go back into the authoring environment and record and respond to all the feedback obtained during the reviewing and testing phase

16

8. Write the Final Draft

This involves the information gathered from the activities of two previous stages

If you do them thoroughly, you will find that your document improves greatly at this stage

Writing the final draft of a help system mainly consists of preparing the help file for distribution with the finished program

17

9. Conduct a Field Evaluation

This special kind of test enables you to gauge how well your manual meet the task needs of intended user

Information from this evaluation usually end up in a evaluation report and provides input for next project

The field evaluation entails gathering feedback from users after the program and help system have been delivered Use feedback links in the HTML forms Use of Email links

18

Recap (Guidelines for Planning a Documentation Project) The documentation process

1. Start the Project

2. Perform the User Analysis

3. Design the Documentation

4. Plan the Documentation Project

5. Write the Alpha Draft

6. Conduct Reviews and Tests

7. Revise and Edit

8. Write the Final Draft

9. Conduct a Field Evaluation

19

20

Summary

Any Questions?