![Technical Communications: Planning ,[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]](https://image.slidesharecdn.com/technicalcommsplanningnf-12776635456072-phpapp02/85/Technical-Comms-Planning-Nf-1-320.jpg)
![Technical Communications: Planning ,[object Object],[object Object],[object Object],[object Object],[object Object]](data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7)
Empfohlen
Empfohlen
Weitere ähnliche Inhalte
Ähnlich wie Technical Comms Planning Nf
Ähnlich wie Technical Comms Planning Nf (20)
Kürzlich hochgeladen
Kürzlich hochgeladen (20)
Technical Comms Planning Nf
Hinweis der Redaktion
- One of the most fundamental decisions you have to make as a writer is when to start writing. The planning and preparation stage of the writing process is like focusing your camera on a subject before taking a photograph. First determine what your purpose is, what your objective is, who your reader is, and what your scope of coverage should be. You will then be able to create a realistic project schedule. Clear writing is the result of a careful and methodical approach.
- During analysis, find out what information the users need and decide what set of documents should be developed to meet those needs. Address the product in its totality, including product description and usage. The software, marketing material, technical documentation, training material, and customer support information should complement each other, with no gaps or conflicts of information. For example, whenever training needs analysis is performed, documentation needs analysis should be performed as well. It would also be ideal to have a Customer Service and Help Desk representative participate too. This will help produce a consistent and smooth information delivery system for a solid post-sales information support framework. We also need to think about pre-sales functions, such as marketing research and beta-testing programs. Most of the time tech writers are flying in the dark. They need to be involved in product development—right from the start. It would be ideal if writers could interview and meet with prospective users at an early stage in the documentation process—maybe even having prospective users review documentation drafts—much like when users beta test the software.
- For each type of user, compose a list of tasks he or she will carry out when using the product. Specify the following for each group of tasks: Why the tasks are carried out? What is the sequence in which the tasks are carried out? What are the prerequisites for the tasks? When and how frequently are the tasks carried out? And what sub-tasks are needed to carry out the tasks?
- Analyze how users learn about and use the product over time. This will help to clarify what type of information users will need at various stages. Also consider how the user’s information interface progresses. For instance, from graphics to text, from tutorial to reference, from an informative web page to a utilitarian interface. And what information becomes more or less useful over time. For example, once the user becomes well-informed about a product, he or she may see the tutorial as less important, and the reference guide as more important, and therefore, useful. Arrange to provide suitable documentation for all phases of the user’s learning curve; and ensure that all documentation is consistent, with clear transitions between each phase, thus establishing a seamless knowledge-development path for the user.
- Information should be collected about users and the tasks they’ll carry out while using the product. Work with others on the project to collect and agree to the types of information that’s relevant to the defined user profile. Ideally, information about users should be collected directly from those users. For a set of documentation, individual documents in the set can be for particular user groups. Determine the knowledge level for each user profile: their assumed computer systems experience; their knowledge of the assigned task; their expected knowledge of similar products; and their language and culture.
- Think about the ‘physicality’ of your information interface and delivery channel: analyze the user’s physical working environment. For example, should you provide print only? And what about binding? Will you need online documentation and multimedia? Is there a need for direct user access? database delivery to the user? and trigger points in a process for more information?
- How about required user input? Is there a need to notify a particular user or group of users at a particular time? What channel should be used for this notification? Analyze the information on the application’s Graphical User Interface (GUI) and ensure that your documentation complements, is consistent with, and refers to the GUI content.
- An essential component of the quality control function is establishing and maintaining the appropriate scheduling, developing, and testing of documentation (i.e., product support information) in parallel with the scheduling, developing, and testing of the associated software (i.e., product functional/operational information). A documentation plan supports product quality objectives by providing a solid starting point, a roadmap, and a barometer for the documentation project. The plan may change as the project evolves; but at the very least, it keeps all documentation team members in-step at all times.
- To clarify what your project role is as the writer, it’s important to list the following ‘Documentation Services’ in the documentation plan: research, interviewing, testing (e.g., when documenting software with a GUI interface), editing, writing, formatting, layout, graphics, and multimedia, and draft review preparation, coordination, and administration.
- Other services include document validation for content and versioning, document control and standards, production editing and coordination, vendor coordination (if applicable), project management (for documentation tasks), document packaging, and document distribution.
- The ‘Product Background’ section of the plan discusses the developmental stages of the new product, or it can provide historical information regarding the enhancements and revisions of existing products. ‘Product Description’ briefly describes product fundamentals, features, functionality, and general usage. The ‘Business Case’ describes the business objective that may relate to marketing, contractual, or customer input requirements. The ‘Purpose’ of the documentation describes what the documentation is meant to achieve for its intended audience.
- ‘ Scope’ identifies the characteristics of the documentation (e.g., the set of documents involved, if it’s a re-write, an update, a brand-new product, etc.) and the extent of the subject matter it’s meant to cover. The ‘Intended Audience’ defines the audience profile, for example: internal users, departmental users, or external users. ‘Related Documentation’ lists other documentation related to this product or to the document. ‘Documentation Producers and Administrators’ identifies the producers (e.g., a Technical Writer, a Software Engineer, a Marketing Representative, a Training Representative, and others) and the administrator of the documentation, which is most likely the Technical Writer.
- ‘ Information Sources’ specifies the information source; including, but not limited to, the following: interviews with management, customers and users, developers, and system administrators; attending internal training sessions; attending technology knowledge transfer sessions; existing documentation and functional specifications; and testing results. A ‘Product Development Resource’ provides names, roles, responsibilities, schedules, and a means of knowledge transfer for development, training, marketing, and management personnel. A ‘Customer Input Resource’ provides names, roles, responsibilities, schedules, and a means of knowledge transfer for internal resources (e.g., a product manager) and external resources (e.g., customer and beta users).
- The ‘Draft Review’ describes what the draft review entails (e.g., online viewing for gathering comments, distributing printed versions of the draft for hard-copy markups, arranging for a draft review meeting with all reviewers, etc.). ‘Conflict Resolution’ describes contingency plans to gain a final decision. For example, escalating conflicts regarding draft documentation by way of a peer group/reviewer meeting to gain consensus; escalating conflict to relevant managers, or meeting with managers to gain consensus.
- The ‘List of Reviewers’ provides a comprehensive list of draft reviewers (including external reviewers, if appropriate). This list can be broken down per chapter, per draft review, or per document (in the case of a documentation set). ‘Document Preparation’ identifies what standards, if any, this documentation adheres to; for example, ISO 9000, Section 508, and others. It also describes the software tools used to produce the documentation; for example, word processing and desktop publishing applications, graphics tools, and HTML/XML editor programs.
- ‘ Packaging and Format’ indicates the required media for the documentation, and the reasons why (e.g., ergonomics, cost, customer requests, or restrictions); and if it’s print or online (e.g., windows help, CD, web-based, SGML, HTML, XML, and others). If in print format, the binding requirements (e.g., ring, comb, perfect, and others) and any special paper sizes or other requirements are provided. ‘Information Strategy’ can include strategies for documentation input and output (e.g., user interactivity, using conditional text, pull versus push, information architecture, etc.). Strategies can also be described for the draft review cycle, for re-usable and modularized documentation, and others.
- The ‘Documentation Schedule’ refers to planned phases. Each document must have a definitive schedule that includes draft reviews commensurate with the software product development and testing stages. ‘Documentation Contents’ provides a preliminary outline or table of contents (with page counts, if possible) per document. ‘Definitions, Acronyms, and Abbreviations’ defines terms, acronyms, and abbreviations in accordance with the audience profile.
- ‘ Documentation Control and Distribution’ describes such things as documentation storage and access, process automation, and updated releases. Determine an accepted version numbering system, date format, document header and footer information, a master list of all documentation, distribution mediums (e.g., print, CD, DVD, HTML, XML, and others), a version control and distribution policy (e.g., a shredding policy for print documentation), online requirements (e.g., user viewing requirements and restrictions), the administrative process, and so forth.
- ‘ Knowledge Transfer Requirements’ relates to documentation development, including knowledge transfer channels and their participants. For example, a software engineer presents a product overview while the technical writer takes notes, or a technical writer provides feedback to the developers after testing the graphical user interface, or provides developers with conflicting draft review comments or customer feedback regarding the current version of the software and/or the documentation.
- The following is a list of assumptions that all documentation team members must agree upon: 1) The writing effort for this project depends on adherence to the published software development schedule, availability of technical input to the writer, and thorough and timely reviews of all drafts.
- 2) Information sources allocate an appropriate amount of time within the software development schedule to meet with the writer for thorough and accurate information gathering during the initial stages, and confirm the thoroughness and accuracy of information on a timely basis throughout the draft review process. Conflicts regarding draft documentation content are resolved in a timely and professional manner.
- 3) Any changes to the software development schedule or scope of the project will mean a change in the documentation schedule. 4) The main sources of information for the documentation are design and functional specifications, access to engineers, developers, operations staff, managers, marketing representatives, customer representatives (including external customers), testing results, existing documentation, the hardware and software, and so forth.
- 5) The writer will interview the appropriate people for relevant information, and will have regular access to them on an ‘as-needed’ basis. 6) The writer agrees to provide, for review: a rough draft, a first draft, and a signoff draft of the document. To facilitate the draft review process, and to minimize extensive changes during review and production, management and staff agree to the following: Managers will delegate members of their group to review and to provide comments regarding the draft document.
- Once management has signed off on the final version of the document, they will not see the document again until the document is copied and distributed (that is, they agree not to submit changes to the document during the production cycle). This minimizes changes made to the reproduction-quality copy. Any changes to these assumptions, contents of the documentation, and/or delays in draft review response time, may necessitate a revision to this documentation plan.