planning and writing your document itsw 1410 presentation media software instructor: glenda h....

Planning and Writing Your Document

ITSW 1410

Presentation Media Software

Instructor: Glenda H. Easter

Planning & Writing Your Documents, Chp. 4

2

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.


3

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.


4

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.


5

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.


6

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


7


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.


8


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?


9


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


10


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.


11

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.


12

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.


13


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.


14


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.


15


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.


16


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.


17

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.


18

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.


19

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.


20

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.


21

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.


22

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.


23

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 procedureDefinition of a command with an exampleDefinition of a term related to the program.Labeled screen with explanations of the interface,


24


– All of your online help will be organized in the following manner:

ProceduresShortcutsBackgroundGlossary TermsMenu CommandsFrequently Asked Questions (FAQs)

2. Determine the Interconnected Elements


25


3. Decide What Affordances to UsedAffordances 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.


26

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.


27

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


28


– It describes the documentation process or the project plan. (Continued)

The schedulesThe resourcesTime/Page estimatesMay contain appendixes about the users of the

program.


29


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.


30


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.


31


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


32


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;


33


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


34


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 resourcesTime/Page Estimates


35


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.


36


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.


37


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.


38

Alpha Draft I Manual Checklist Content ElementsHave Need Feature Installation Copyright/warranty/disclaimer Introduction to the program

(important features, graphic overview)

Introduction to the users (groups, name and describe each, scenarios, graphic overview)


39

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:


40

Alpha Draft I Manual Checklist (Continued)

Format Elements Have Need Feature

Headers Footers Rules Page numbers Cut marks New ideas for document improvement:


41

Favorite Links to Visit

Http://www.microsoft.com