Planning and Writing Your Document ITSW 1410 Presentation Media Software Instructor: Glenda H....
-
Upload
sherman-haynes -
Category
Documents
-
view
213 -
download
1
Transcript of 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.
Planning & Writing Your Documents, Chp. 4
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.
Planning & Writing Your Documents, Chp. 4
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.
Planning & Writing Your Documents, Chp. 4
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.
Planning & Writing Your Documents, Chp. 4
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).
Planning & Writing Your Documents, Chp. 4
7
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. 4
8
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. 4
9
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. 4
10
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. 4
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.
Planning & Writing Your Documents, Chp. 4
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.
Planning & Writing Your Documents, Chp. 4
13
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. 4
14
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. 4
15
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. 4
16
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. 4
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.
Planning & Writing Your Documents, Chp. 4
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.
Planning & Writing Your Documents, Chp. 4
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.
Planning & Writing Your Documents, Chp. 4
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.
Planning & Writing Your Documents, Chp. 4
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.
Planning & Writing Your Documents, Chp. 4
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.
Planning & Writing Your Documents, Chp. 4
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,
Planning & Writing Your Documents, Chp. 4
24
Overview of the Online Help Development Process
– All of your online help will be organized in the following manner:
ProceduresShortcutsBackgroundGlossary TermsMenu CommandsFrequently Asked Questions (FAQs)
2. Determine the Interconnected Elements
Planning & Writing Your Documents, Chp. 4
25
Overview of the Online Help Development Process
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.
Planning & Writing Your Documents, Chp. 4
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.
Planning & Writing Your Documents, Chp. 4
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
Planning & Writing Your Documents, Chp. 4
28
The Documentation Plan (Continued)
– It describes the documentation process or the project plan. (Continued)
The schedulesThe resourcesTime/Page estimatesMay contain appendixes about the users of the
program.
Planning & Writing Your Documents, Chp. 4
29
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. 4
30
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. 4
31
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. 4
32
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. 4
33
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. 4
34
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 resourcesTime/Page Estimates
Planning & Writing Your Documents, Chp. 4
35
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. 4
36
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. 4
37
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. 4
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)
Planning & Writing Your Documents, Chp. 4
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:
Planning & Writing Your Documents, Chp. 4
40
Alpha Draft I Manual Checklist (Continued)
Format Elements Have Need Feature
Headers Footers Rules Page numbers Cut marks New ideas for document improvement:
Planning & Writing Your Documents, Chp. 4
41
Favorite Links to Visit
Http://www.microsoft.com