1. 1 Technical & Business Writing (ENG-315) Muhammad Bilal Bashir UIIT, Rawalpindi

2. Outline 1. Guidelines for Planning a Documentation Project 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 2. Summary 2

3. Planning and Writing Your Documents Lecture: 16 3

4. 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

5. 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

6. Plan the Documentation Project (Continue…) Decide What to Schedule  Meetings  Deadlines for drafts  Project report due dates  Test completion  Review deadline  Edits 6 EventStart DateEnd DatePersonnel Complete user analysis 15/4/20121/5/2012Manager, writer, user group Progress Report15/5/ 2012Manager Write draft21/6/20127/7/2012Writer Editing9/8/201225/8/2012Writer, editor

7. 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 TypesAttendancePurpose Review MeetingAll persons who review a draft Go over the review information and resolve conflicts User Walkthroughs Selected usersGo over the documentation design plan for suitability, ease of use and usability Technical Walkthroughs ProgrammerGo over the program task list for inaccuracies, omission and logics

8. Plan the Documentation Project (Continue…) Kinds of reports associated with the documentation process 8 ReportWriterReaderDescription EvaluationTeam leaderSupervisor/ Sponsor Describe and evaluate work of team member ProgressWriter/ Team leader Manager/ Client Describe work to date and plan for completion TestWriter/ 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

9. 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 project8 2. Perform the user analysis15 3. Write the project plan15 4. Design the document8 5. Write the alpha draft15 6. Conduct reviews and test15 7. Revise and edit8 8. Write the final draft8 9. Conduct a field evaluation8 Total100

10. 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

11. 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

12. Plan the Documentation Project (Continue…) 12 Activity: creating a basic calendar Operation Needed Page lengthScreen shots Total Long = 1 Med =.5 Short =.25 Include =.5 Spot graphics =.25 Not needed = 0 Creating a Calendar1.51.5 Importing an Image1.51.5 Changing the Typeface.5 1 Insert text on Date.5.25.75 Printing a Calendar1.51.5 Saving a Untitled Calendar.50 Total Pages6.75 Total Hours19.575

13. 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

14. 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

15. 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

16. 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

17. 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

18. 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

19. 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. 20 Summary Any Questions?