Planning and Writing Your Documents Chapter 6

Start of the Project Start the project by knowing the software you will write about, but you should try to know more about the user than the software. Most software documentation is created by two kinds of teams: development teams and writing teams. On the development team you work as the writer or editor with other professionals who do the programming, planning and marketing of the product. Writing teams consist of people who write, edit or test documents.

The Development Team Product Developer – The product developer designs the software program and are often the subject matter expert. Product Manager – Organizes the project, assigns tasks, and keeps the project on track. Often this person has a background in business management or organizational strategies. Market/Systems Analyst – Studies the user situation and models the activities that the program will automate. They make the product a commercial success. Technical Specialist / Programmer Documentation Specialist

The Writing Team Manager – Takes charge of the overall project and keeps it on track by creating and maintaining a schedule; meeting with the developer, client, project supervisor, tracking progress, meetings etc. In charge of the documentation plan. Lead Writer – Conducts the user analysis and writes up the program task list and drafts of documents and topics. Develops the research information into actual drafts. Writer – Create content for a project, or rewrite preexisting content according to the documentation plan. They interview SME or researching information. Editor – Creates a style guide for the team members to follow and edits the document to make sure they are consistent. Takes charge of production duties for the team. Graphics Designer – Handles technical aspects of screen captures and create illustration and artwork for the team. Tester – Conducts usability testing.

Overview of Help Development Process An online help system is a document that is delivered as software using the stand- alone Win Help format or an HTML format. Online help is also delivered in PDF, a format that uses a page layout but allows for hypertext link. Online help contains information about program operations and the interface of the program, arranged and presented within the context of the users’ complex workplace activities. This online help system organizes program operations according to categories that are meaningful to users.

Perform the User Analysis During this stage you research a number of elements pertinent to effective software use, mainly focusing on the workplace activities of your users that involve software. Analysis of the user means interviewing and observing them in order to determine their user type, learning preferences, and other elements. The activities in the user analysis should allow you to group the program operations for your table of contents. The default manual merely describes the interface and can be written without a user analysis. The task-oriented manual arranges the program interface information in meaningful ways based on a user analysis.

Design the Documents During this stage you apply three types of document forms – tutorials, procedures, and reference – to your user’s needs. The design phase also means that you outline the documents and decide about their layout: pages, text style, size, font, and language. For online help, you will need to decide on the type of products you will produce (help, training, guided tour, templates, messages, tips etc) Document decisions at this phase are important for planning but may change over time. Prepare prototypes and test it.

Write Project Plan Set documentation goals Identify and assemble the writing team Identify and negotiate project resources Arrange for design testing and reviewing Set up a project schedule Circulate project plan to team members – this consists of three main parts: A. Schedule of events for completion of your project B. Plans for using resources B. Plans for using resources C.Time/page estimates C.Time/page estimates

Study Table 6.2 – Kinds of Meetings Associated with the Documentation Process (pg. 192) Table 6.3 – Kinds of Reports Associated with the Documentation Process (pg. 193)

Write the Alpha Draft Carry out writing tasks identified in the project plan Test prototype designs and drafts with the users Maintain the style sheets for the project Maintain project records and archives

Conduct Reviews and Drafts Get user reviews for suitability, accuracy, and completeness. Arrange for technical reviews and review meetings. Contact users for usability tests. Make arrangements for use of usability lab. Conduct usability tests. Write a usability report. Maintain project records and archives.

Revise and Edit Incorporate review information into drafts. Reconfirm changes with users. Schedule document edits. Schedule review meetings. Assemble and manage all the graphics. Review graphics and tables for accuracy. Maintain project records and archives.

Write a Final Draft Confirm vocabulary decisions with users Maintain the file system for drafts Write the index and appendix if necessary Maintain project records and archives.

Conduct a Field Evaluation Survey actual users for reactions, needed improvements. Contact customer support for records of user questions. Write an evaluation report on the project. Maintain project records and archives.

Methods of Document Development The Waterfall Method: This method of software development depends on understanding the users’ requirements at the beginning of the project and then carefully designing a system to meet them. Ideally, each phase is done before the next begins. The Rapid-Development Method: This method uses a process of usability testing and prototyping to test designs during development. Once the right design is found the program is complete. User requirements are refined as the product unfolds. The Object – Modeling Method: This method uses a complex system of symbols and descriptions to create an abstract design for the system that can be turned into software and documentation with a high degree of consistency.

Two Parts of a Documentation Plan The documentation plan does 2 things: The first part is the design plan, tell what your manuals will contain (content) and what they will look like (forms, layout, language, graphs etc) The second part is the project plan, tell how you will produce your manuals: the schedule, resources, and time / page estimates. Study Table 6.5 (pg. 209)