Planning and Writing Your Document ITSW 1410 Presentation Media Software Instructor: Glenda H. Easter

Planning & Writing Your Documents, Chp. 42 Write the Project Plan The project plan allows you to specify the items you determined during the design phase, and add information about the entire project. –To do this you must describe the management aspects of your work: schedules of drafts and tests, people and hardware resources, and time/page estimates.

Planning & Writing Your Documents, Chp. 43 Write the Project Plan (Continued) The project plan culminates your research and design work on a project. You can apply appropriate predictive testing to the project plan before going on to the next stage in order to insure appropriate document and project guidelines.

Planning & Writing Your Documents, Chp. 44 Guidelines for Planning a Documentation Project Create a task list. Work backwards from the delivery date. Assign people to tasks. Work in the drop-dead mode. Make the documentation plan persuasive.

Planning & Writing Your Documents, Chp. 45 Planning a Project Create a Task List: The main advantage of the task sheet lies in the ability it gives you to tick off your accomplishments as you work. Work Backwards from the Delivery Date: Once you have a task sheet you should try to estimate how long each task will take. –You can estimate the times it will take for the separate phases of the development by adding up the total times for tasks for each state.

Planning & Writing Your Documents, Chp. 46 Planning a Project (Continued) Work Backwards from the Delivery Date: –Estimating times for various phases gives you an overall perspective of the time requirements. –After you have a general idea of how long you will take on each task, arrange the tasks in order from the last task to the first tasks. –This allows you to find milestones (those dates that projects are completed).

Planning & Writing Your Documents, Chp. 47 Planning a Project (Continued) Work Backwards from the Delivery Date: –Once you have arranged the tasks starting with the due date, you may not have the amount of time to complete the project. If this occurs, you may have to compromise on tasks. Assign People to Tasks: –Try to assign people to tasks as early as possible.

Planning & Writing Your Documents, Chp. 48 Planning a Project (Continued) Assign People to Tasks: –Review the skills of those on the project and try to match team member skills with specific tasks. Utilize their greatest area of expertise. Work in the Drop-Dead Mode: –If you drop dead today, could someone else come in and pick up the project exactly in the same spot?

Planning & Writing Your Documents, Chp. 49 Planning a Project (Continued) Ways to Maintain a Project: –Progress reports/project diary. Keep a list of the hours spent on each project and the types of activities completed. –Work record sheets or maintaining an actual log of the work done. –Librarianship (Keeping track of all the program files and making lists of files for participants.)

Planning & Writing Your Documents, Chp. 410 Planning a Project (Continued) Ways to Maintain a Project-- (Continued): –Project databases with time and costs for future projects that are similar. Make the Documentation Plan Persuasive: –Use a clear executive summary in your plan that explains people’s obligations. –Your documentation plan functions as a pitch as well as a managerial document.

Planning & Writing Your Documents, Chp. 411 The Documentation Process There is a nine point documentation process that assumes that steps and procedures have been tested at various checkpoints. 1. Perform the User Analysis. 2. Develop the Program Task List. Systematize all the program functions in a logical way. Each task gets defined according to who does what and what is accomplished and which steps are required for completion.

Planning & Writing Your Documents, Chp. 412 The Documentation Process (Continued) 3. Design the Documents: –Apply three types of documents (tutorial, procedures, and reference) to your users needs. –You outline the document. –Decide on page layout, text style, size, font, and language. –Write the titles of the documents, and indicate the level of support needed.

Planning & Writing Your Documents, Chp. 413 The Documentation Process (Continued) 4. Write the Project Plan: –Specify the manual and online help identified during the design phase and add information about the entire project. –You have to determine the schedule of drafts and test, people and hardware resources, and time/page estimates during this stage. –You review and test the project before moving forward.

Planning & Writing Your Documents, Chp. 414 The Documentation Process (Continued) 5. Write the Alpha Draft: –You will write your first complete document at this stage. Included will be: text, graphics, appendixes, indexes, and associated documentation. –The alpha draft is tested, reviewed and edited according to the documentation plan. –It’s a good idea to have a alpha draft checklist.

Planning & Writing Your Documents, Chp. 415 The Documentation Process (Continued) 6. Conduct Reviews and Tests: –Design usability tests –Test for elements such as accuracy and task orientation. 7. Revise and Edit: –When you revise and edit, it allows you to submit to an editor or do your own editing. –You rewrite or reorganizing according to recommendations for accuracy at every level.

Planning & Writing Your Documents, Chp. 416 The Documentation Process (Continued) 8. Write a Final Draft: –If you incorporate all of the feedback into your document, you will have a camera ready copy of your manual. 9. Conduct a Field Evaluation: –This test helps you to gauge how well your manual met the task needs of the intended user. –This information ends up in an evaluation report.

Planning & Writing Your Documents, Chp. 417 Planning Online Help Systems If you decide to provide online help, you will have to work with smaller chunks and plan very carefully how the user will access them. Help systems are the most widespread form of online writing. This includes: –The series of indexes and topics contained in a special program. –Help systems use indexes as the main access element of information.

Planning & Writing Your Documents, Chp. 418 Planning Online Help Systems (Continued) You use groupings or topic categories when developing a help system. A help system allows you to build a significant task orientation into your documentation plan.

Planning & Writing Your Documents, Chp. 419 Benefits of Online Help for the User Provides fast access to information. Offers more features than print. Provides greater convenience than books. Avoids preconceptions of books. Allows interaction with the document. –Allows users to create their own paths.

Planning & Writing Your Documents, Chp. 420 Drawbacks of Online Help for the User Requires more learning because the user must become familiar with the kinds of buttons, pop- ups, links and other features of your specific system. Intimidates novice users. Looks strange. Many users haven’t much experience with electronic books and have difficulty understanding the concept of an online help system.

Planning & Writing Your Documents, Chp. 421 Drawbacks of Online Help for the User Has limited uses: –You can’t use on-line help for installations. –You have to print separate documentation for installation.

Planning & Writing Your Documents, Chp. 422 Benefits and Drawbacks of Online Help, for the Writer Benefits: –It saves paper. –Updates easily. Drawbacks: –Takes up disk space (sometimes more than one to two megabytes of disk space). –Requires reformatting of print. –You will have to reformat your hard copy of the documentation to make it suitable for online.

Planning & Writing Your Documents, Chp. 423 Overview of the Online Help Development Process Plan the project phase to include extra time. The Process for Developing Online Help: 1. Identify and list the Online Help Topics to include: Steps for performing a specific procedure Definition of a command with an example Definition of a term related to the program. Labeled screen with explanations of the interface,

Planning & Writing Your Documents, Chp. 424 Overview of the Online Help Development Process –All of your online help will be organized in the following manner: Procedures Shortcuts Background Glossary Terms Menu Commands Frequently Asked Questions (FAQs) 2. Determine the Interconnected Elements

Planning & Writing Your Documents, Chp. 425 Overview of the Online Help Development Process 3. Decide What Affordances to Used Affordances means the software capabilities that you can build into a help system. 4. Select a Development Method Organize Your Writing Team for both online and hardcopy manuals: –Development Team to develop the entire product (software and documentation) –Writing Team to develop the documents.

Planning & Writing Your Documents, Chp. 426 The Documentation Plan To make it persuasive: –Write an executive summary. –Have a goal orientation. –Do the math. –Show a team orientation. To make it easy to follow: –Standardize your terminology –Clarify the interconnectivity of information units.

Planning & Writing Your Documents, Chp. 427 The Documentation Plan (Continued) To make it easy to follow: (Continued) –Include sample pages. –Put a great deal of detail in the outlines. Purpose of the Documentation Plan: –It describes the manuals or the design plan. –It describes the documentation process or the project plan. How you will produce the manuals

Planning & Writing Your Documents, Chp. 428 The Documentation Plan (Continued) –It describes the documentation process or the project plan. (Continued) The schedules The resources Time/Page estimates May contain appendixes about the users of the program.

Planning & Writing Your Documents, Chp. 429 The Documentation Plan (Continued) What Goes Into the Design Plan? –Describe the users and their level of expertise and some of the tasks they will perform. –Set out the documentation objectives and what it will produce. –Components of an Objective which generally contains three things: the user of the manual, the tasks the user will perform, and the level of task support.

Planning & Writing Your Documents, Chp. 430 The Documentation Plan (Continued) What Goes Into the Design Plan? (Continued): –Include the different kinds of goals –Describe the manual types which will describe in detail the content and layout of the documents. –Determine the Help Topics –Provide Outlines of Individual Documents: Name of the document and the estimated number of page.

Planning & Writing Your Documents, Chp. 431 The Documentation Plan (Continued) What Goes Into the Design Plan? (Continued): –Complete section titles and other divisions of information in the document outlined individually. Possible Help Topics: –Daily tips –Shortcuts –Macro hints –Most frequently asked questions –Advanced keyboard skills –Creative adaptations –Use of software in work groups

Planning & Writing Your Documents, Chp. 432 The Documentation Plan (Continued) What Goes Into the Design Plan? (Continued): –Lay Out Individual Documents with reference to thumbnail sketches and sample pages. –To specify the layout for your documents, you should include the following information: page size; column specifications (for all page types); table specifications (for all table types); body, text style, size, font;

Planning & Writing Your Documents, Chp. 433 The Documentation Plan (Continued) –To specify the layout for your documents, you should include the following information: (Continued) Style specifications for: section and other headings, task names, steps; cueing patterns; notational conventions; binding and boxing specifications; any special formatting or page layout instructions.

Planning & Writing Your Documents, Chp. 434 The Documentation Plan (Continued) What Goes Into the Project Plan? –You introduce the following subsections with a brief one or two line overview: Schedule of events for completion of project. Plans for using resources Time/Page Estimates

Planning & Writing Your Documents, Chp. 435 The Documentation Plan (Continued) What Goes Into the Project Plan (Continued): –Estimate how long things will take. –Calculate time/page estimates Calculate the number of overall tasks multiplied by the average page length for each task. Add in extra pages for front matter and count cover pages and all other pages. Multiple the grand total of all pages that you will produce by the industry standard of 2.9 hours per page.

Planning & Writing Your Documents, Chp. 436 The Documentation Plan (Continued) What Goes Into the Project Plan (Continued): –Decide what to schedule for all overall phases of document development. Overlap Development Process Phase to include: –scheduled meetings, deadlines for drafts, project report due dates, test completion, review deadlines, and edits.

Planning & Writing Your Documents, Chp. 437 The Documentation Plan (Continued) Reviewing Documentation Plan –Hold a user walkthrough (going over the important design elements of your document). –Hold a technical walkthrough (going over the accuracy and completeness in the program task list.

Planning & Writing Your Documents, Chp. 438 Alpha Draft I Manual Checklist Content Elements HaveNeedFeature  Installation  Copyright/warranty/disclaimer  Introduction to the program (important features, graphic overview)  Introduction to the users (groups, name and describe each, scenarios, graphic overview)

Planning & Writing Your Documents, Chp. 439 Alpha Draft I Manual Checklist (Continued) Overview of the doc set (name and forecast sections and uses of sections, graphic overview) –Suggested uses of the program (scenarios, graphic overview) –Tips for efficient use (lists, tables, scenarios, graphic overview) –Table of contents (high detail, moderate detail, low detail) –Index –Other:

Planning & Writing Your Documents, Chp. 440 Alpha Draft I Manual Checklist (Continued) Format Elements HaveNeedFeature  Headers  Footers  Rules  Page numbers  Cut marks New ideas for document improvement:

Planning & Writing Your Documents, Chp. 441 Favorite Links to Visit