As a member of a publications department, your charter is to develop, write, edit, validate, and publish documentation that supports the information needs of your customers.
This appendix provides guidance to help you meet the goals of that charter by giving you information on aspects of publications departments ranging from staffing concerns to technical review procedures. It is primarily intended for companies undergoing rapid growth in their documentation requirements. While most publications-related issues are covered, this appendix does not deal with general management issues such as hiring or personnel reviews.
Topics discussed include:
“Establishment of a Publications Department” on page 274
“Scheduling” on page 282
“Documentation Process” on page 284
“Internationalization and Localization” on page 293
“Online Documentation Considerations” on page 294
“Final Print Production” on page 296
“Post-Production Considerations” on page 300
For a list of books that cover the topic of management issues in more detail than can be provided in this appendix, see the section “Project Management” in Appendix D, “Recommended Reading.”
Note
Note — This appendix explains how the publications department fits into a software computer company’s organization as an example, so you might have to modify some of the recommended processes and procedures to match your own situation.
The documentation presence in a company usually begins with a few people producing written material to accompany products. Publications departments can range from a single permanent publications manager working solely with outside contractors to a department featuring several writing, illustration, and production groups. Table A-1 describes the maturity levels of documentation organizations and their goals at each level.[1]
Use this table to see where your department fits on the continuum. When analyzing your organization, judge its performance as a whole over a long period of time. Although your organization might exhibit some features of a particular level, one instance does not define your organization as having achieved that level of maturity.
Table A-1. Process Maturity Levels of Documentation Organizations
Level | Description | Publications Project Management | Transition to the Next Level |
|---|---|---|---|
Level 0: Oblivious | Unaware of the need for professionally produced publications. Publications are produced by anyone who is available and has time. | None | Staffing with professional technical communicators |
Level 1: Ad hoc | Technical communicators act independently to produce publications with little or no coordination. They may be assigned to different technical managers. | None | Development of a style guide |
Level 2: Rudimentary | The beginning pieces of a process are going into place. Some coordination occurs among the technical communicators to assure consistency, but enforcement is not strong. | None to very little | Introduction of some project planning |
Level 3: Organized and repeatable | A sound development process is in place and being refined. People are being trained in the process. Project management is in the beginning stages, with senior technical communicators learning the rudiments of estimating and tracking. | Introduction of project management | Strong implementation of project planning |
Level 4: Managed and sustainable | Strong project management is in place to ensure that the publications-development process works. Estimating and tracking of projects are thorough, and controls are in place to keep projects within budgets and schedules. Innovation gains importance within the strong existing structure. | Strong commitment to project management | Beginning of the implementation of more effective processes |
Level 5: Optimizing | Everyone on the teams is engaged in monitoring and controlling projects. As a result, effective self-managed teams are becoming the norm. Innovations in the development process are regularly investigated and the teams have a strong commitment to continuous process improvement. | Strong commitment to project management and institution of self-managed teams | Strong and sustainable commitment to continuous process improvement |
If you want to expand your department, the first step is usually to convince management of its value. However, measuring the “value added” of accurate, comprehensive documentation written by professional technical communicators is not easy. Your focus is on added ease-of-use for the user, in the product interface as well as the documentation. However, that is often not as important an argument to management as actual costs saved.
This section provides some ways in which you can show how good documentation adds value and offers some metrics from other studies that you can use.[2]
Traditional accounting practices often make showing the benefits of improving quality very difficult. For example, many accounting systems still track costs by department rather than project. If customer support costs go down, the customer support group looks good. The documentation group does not get any credit for reducing support costs, even if good documentation contributed substantially to the reduction.
Many accounting systems are still based on a manufacturing model rather than a labor-intensive service model. For example, a documentation group that is measured only on pages per day appears to cost more if their higher-quality documents have fewer pages. Value that the documentation group is adding through activities other than writing and production (such as interface evaluation) or the greater benefits of shorter documents might not be reflected in the accounting reports.
When considering the value added by a professional publications staff and good documentation, costs avoided are as significant as costs saved. For example, say a company gets 100,000 support calls a year at a cost of $30 a call. If better documentation reduces the call volume by 10 percent (either the number of calls or a shorter duration of call), the technical communicators save the company $300,000 a year.
Another aspect you can point out is the cost per problem at different points in the product development cycle. Problems found in the writing/editing cycle are much less expensive to fix than problems found once the product is in the field.
Measures that show increased benefits resulting from good documentation include:
More sales
Increased productivity
A higher percentage of forms or response cards returned
Forms or response cards returned more quickly
More users’ problems identified early in the process
Measures that show reduced costs resulting from good documentation include:
Fewer support calls, which results in lower support costs
Less need for training, which results in lower training costs
Fewer requests for maintenance, which results in lower maintenance costs
Less time needed for translation, which results in lower translation costs
Less effort (time, lines of code, rework) when technical communicators are involved early in the development process than when they are not
Lower costs for writing, paper, printing, and so on because technical communicators showed developers that they did not need all the documentation that they were planning
Fewer errors in specifications written by technical communicators than in specifications written by engineers
When trying to find ways to illustrate value added by good documentation, consider the following techniques:
Estimating avoidable costs from historical data, for example, costs of writing and sending updates and bulletins about problems and solutions, support costs, and costs to the customer’s company.
Comparing two documents or two situations in which one document used the services of publications personnel and the other document did not. For example, you might submit a previous version of a document that has been revised, or interview users who have access to the documentation and those users who do not have access.
Companies, especially those with fledgling publications groups, often regard documentation as merely writing down what the product does. You should also try to establish a role as the user advocate. You can offer your expertise during the project development stage in areas such as interface evaluation, menu item and error message wording, usability, and so on. If you encounter resistance to early writer involvement, point out that problems like inconsistent interface features take much less time, and therefore less money, to correct at early stages in product development than if the writers are not involved until the actual writing cycle begins.
Once you’ve convinced management that your department should be expanded, you might be asked to help determine how your publications department is funded.
Some possibilities for funding are as follows:
Funding by the division to which the publications department reports regardless of who receives the documentation services. For example, a publications department might report to and be funded by the marketing division even though the department is developing documentation for the engineering group.
Funding for department personnel from the budget of the project they are documenting. The publications manager identifies the staffing level required for a given project and the positions are funded by the project’s budget.
Funding for centralized services such as editing, illustration, and production by the division to which the publications department reports, with individual writers funded by the project they are documenting.
Obviously, each scenario has advantages and disadvantages. For example, if you are a writer reporting directly to an engineering project manager, you will probably have a closer relationship with the engineers on the project than if you are a member of a separate publications department. At the same time, your concerns as a publications-oriented team member might not be taken as seriously in an engineering group as they would if you reported to a publications manager.
When you have permission to expand your staff, consider the roles your staff members need to fill. The following sections describe the roles of various publications personnel. Smaller departments or projects might need to combine these functions.
Supervises all personnel matters: recruiting, hiring, training, supervising, and evaluating
Plans and schedules projects, and might oversee them
Acquires and allocates resources: monetary, personnel, equipment, outside resources
Works with project initiation, design, and planning teams
Coordinates and maintains the documentation plan (see “Writing a Documentation Plan” on page 284 for more details)
Coordinates and tracks schedules
Assigns writing tasks to individual writers and consults with them to set priorities
Makes sure technical or hardware problems encountered by writers are resolved
Represents the writing team at project team meetings or other department meetings relating to the project
Holds weekly meetings of the writing team and issues weekly status reports
Coordinates multiple technical reviews
Serves as the liaison with the production staff
Determines scope and contents of assigned books with input from the project writing team and relevant departments such as marketing and usability testing
Writes the documentation plan if there is no writing team leader (see “Writing a Documentation Plan” on page 284 for more details)
Gathers and verifies source data, which includes attending engineering and product design meetings
Disseminates project information to the rest of the documentation team
Writes the documentation according to the audience and technical content defined in the documentation plan
Develops or works with an illustrator to create illustrations
Incorporates editorial and technical review comments
Arranges for validity and usability testing
Directs and guides the writers to write clearly and consistently, with the user in mind at all times
Provides editorial support at all levels: developmental editing, copy editing, and proofreading (see “Types of Editing” in Chapter 10, “Working With an Editor”)
Ensures that grammar, syntax, and spelling are correct in all documents
In projects with more than one writer, brings the different styles of the various writers into a consistent whole to achieve a single voice
Maintains the project style sheet
Keeps all writers on a project informed of stylistic decisions, title changes, and so on
Ensures correct use of copyright and trademark information
Checks that all figures and tables (from chapter to chapter and book to book) are consistent in style and quality, are in the right position, and, if appropriate, are numbered correctly
Develops the overall look and design of the documentation product
Determines how typography, use of color, and general layout of the information are handled
Designs graphic elements, such as icons and glyphs, that assist a reader
Possibly produces graphics for the software interface or online documentation
Helps redesign the documentation format for a company, a set of documents, or a single document
Designs packaging and manual covers
Once you have determined who is paying for the publications staff and defined their tasks, you can start hiring staff. One of the primary decisions in this area is whether to hire permanent staff or to use contractors. Small companies might choose to hire a documentation manager who supervises a staff of contractors. Larger companies might have a mixed staff of contractors and permanent writers, or they might hire contractors for peak loads or short-term projects only.
Expertise. Full-time contractors can offer a high level of experience and professionalism. These qualities are especially important if your publications department is young and your processes are not fully in place.
Flexibility. In slow times, you do not need to maintain a full staff.
Opportunity to evaluate prospective employees in real work conditions. More and more companies are using contractors with an option to convert them to permanent staff. This practice enables you to see whether the employee is productive and works well in your environment.
Cost. The cost per hour of contractors is necessarily higher than permanent staff. However, you save on paying for health benefits and vacation, and sometimes the office space and equipment costs, of a permanent position. Also, experienced contractors can often produce documentation quickly.
Learning curve. Contractors are usually unfamiliar with your product, your processes, and the employees of your company, whether in your own department or in other departments from which they need to gain information.
Not only must you allow time for the contractor to “get up to speed,” but the knowledge gained also departs with the contractor rather than benefiting the company.
Also, for editors especially, lack of familiarity with your in-house style and the lack of an established relationship with in-house writers can be difficult factors to overcome.
Accessibility. If contractors are working off site, they are not available for spur-of-the-moment meetings or decision making.
Communication. The adage “out of sight, out of mind” is unfortunately often true when you mix permanent staff and contractors. For example, sometimes tacit agreements on style or processes are made in casual hallway conversations that the contractor misses and that the on-site personnel forget to pass on.
After deciding to hire a contractor, make sure that you consider the following factors:
On-site time commitment. Establish a clear understanding of how much time the contractor is expected to be on site, for meetings or other necessary commitments.
Tax regulations. Make sure that you comply with the regulations of federal, state, and local tax agencies. Some payment agreements and on-site time considerations might affect whether tax agencies will consider contractors as permanent employees.
Non-disclosure agreement. You should have the contractor sign a standard agreement that protects your company’s proprietary information.
Compatible software delivery mechanism. Make sure that the contractor has compatible software and hardware and can deliver easily into your current system.
Delivery of material. Materials such as updated schedules and project style sheets must be delivered to the contractor. Material to be received from the contractor includes drafts or schedule updates. You should have an easy and efficient method of delivery.
If your company has a personnel office, hiring procedures are probably already established. However, if your hiring is less formal, you might need to consider the following tasks:
Developing job descriptions
Determining grade or salary levels for levels of writers, editors, or illustrators
Evaluating the level of seniority needed for a position (for example, could you use entry-level applicants or college interns?)
Establishing the interviewing team (for example, should developers on the project be included?)
Conducting orientation and training
One of the more difficult tasks facing any publications department is developing accurate and realistic schedules and modifying them while the project is underway. This section provides some basic information about schedule estimates and contingencies, but it is by no means exhaustive. For a list of books that deal specifically with managing documentation projects, see the section “Project Management” in Appendix D, “Recommended Reading.”
The following table shows a rough formula for calculating the hours needed for documentation tasks.[3] Keep in mind that these are estimates only and that they might vary depending upon the nature of the documentation. For example, very technical documentation is usually more time-consuming to write and edit than is overview information. Outside factors such as poor source material or limited availability of subject matter experts can also affect schedules.
Table A-2. Productivity Formulas
Activity | Formula for Calculating Hours |
|---|---|
Writing new text | 3–5 hours per page |
Revising existing text | 1–3 hours per page |
Editing | 6–8 pages per hour |
Indexing | 5 pages per hour |
Production preparation | 5 percent of all other activities |
Project management | 10–15 percent of all other activities |
You might want to consider setting up a system to track the amount of time your staff members spend on each project. You can use this data to more accurately predict the amount of time needed for future projects.
When developing the schedule, tie your deliverables to project milestones rather than to calendar dates. Estimate the time before or after a milestone at which you expect to deliver the component (for example, “The first draft of the documentation will be completed two weeks after the alpha version of the software is delivered to Product Test”). That way, you can more easily adjust your documentation schedule to match the progress of the project. Be realistic in your own assessment of actual progress in other departments, such as product development and testing.
The following table shows a typical publications project schedule.
Table A-3. Sample Publications Schedule
Milestone | Date Information |
|---|---|
Engineering specification | Date from engineering |
Documentation plan | Start and end dates |
Alpha software delivery | Due date |
First draft | Due date |
Technical review | Start and end dates |
Developmental edit | Same start and end dates as technical review |
Usability test of draft | Same start and end dates as technical review |
Index development | Same start and end dates as technical review |
User interface freeze | Date from engineering |
Illustrations complete | Due date |
Feature/function freeze | Date from engineering |
Second draft | Due date |
Copy edit | Start and end dates |
Validity testing | Same start and end dates as copy edit |
Final draft | Due date |
Proofread | Start and end dates |
Final draft to production (hard-copy and online versions) | Due date |
Be sure to keep track of changes in delivery dates, and let other departments involved in the project know if a date is going to slip. Setting expectations up front is the best way to establish credibility and to call attention to late deliverables on which your own deliverables depend.
This section walks you through the process of planning documentation, writing it, and getting it reviewed.
The documentation plan informs the rest of the product team about your plans for the product documentation. The plan should be reviewed by representatives of all departments involved with the product. Keep the plan up to date throughout the project, with major changes being announced when necessary.
The documentation plan is based on input from various departments. The following table provides some ideas of the type of information you might get from other departments.
Table A-4. Documentation Plan Input From Other Departments
Department Name | Relevant Information |
|---|---|
Marketing | Product definition, product name, customer profile, feature and function product requirements |
Development | Feature and function schedule, user interface concerns, error message data, names of experts on subject matter |
Legal | Trademarks, product names |
Customer Support | Customer profile, previous product troubleshooting logs, ways to obtain technical support, names of experts on subject matter |
Manufacturing and Operations | Part numbers, product packaging, production schedules, shipping lead time |
The following table lists the components of a typical documentation plan. It is a sample only, and not all sections are relevant to all product types or publications departments.
Table A-5. Documentation Plan Sample Topics
Topic | Content |
|---|---|
Product information | Product name and version, brief description of the product’s intended use. |
Documentation resource requirements | Personnel, equipment. |
Revision information | Differences from the documentation of previous versions of the product if any. |
Documentation objectives | Overall objectives of the documentation set or of each book. |
Documentation overview | Full list of documentation deliverables and the format in which they will be delivered. |
Documentation descriptions | Brief description of the chapters and appendixes in each book, with the estimated page counts. If the books in the documentation set are large, each book might require a separate documentation plan. |
Documentation schedule | Publications schedule milestones and other milestones from the project schedule that affect the documentation. Publications milestones might include draft delivery dates, technical review dates, and the final document delivery date to production. |
Technical review | List of technical reviewers and the projected review schedule. |
Test plan | Plans and dates for validity testing, usability testing, and, if relevant, media testing. |
Edit plan | Editing schedule and book priorities. |
Localization plan | Languages into which the document will be translated, required resources, and schedule. |
Documentation design | Format of the documentation components, including book sizes, online media, and other design details. |
Production plan | Printing and packaging specifications. |
Issues | Any projected issues that might affect documentation, such as suspected schedule slips, engineering uncertainties, or known project design difficulties. |
Critical dependencies | Items needed from other groups, including the due date and the impact if the information is not provided or is late. These dependencies might include the following items:
|
Documentation concerns especially affect product development at two points in the schedule: during technical review and at the end of the project.
Technical review. Your subject matter experts must dedicate time to complete a thorough and expert review of your documentation. Unfortunately, technical reviews usually occur when the development staff is busy with last-minute engineering and bug fixes. Management support is often crucial in making sure that the development staff take the time to review the documentation thoroughly. Documentation must be considered an important part of the product by all departments for technical review to be treated with the attention it requires.
Code freeze. The other development concern arises at the end of the product cycle, when you need to freeze your screen illustrations and descriptions of the product but the development staff is still fixing bugs. Make sure that the developers, and management, realize that the documentation requires production lead time. They also need to realize that changes to the product after the documentation has gone to production are difficult, if not impossible, to incorporate and will cost more.
This section deals with the writing of the documentation and with the hand-offs the writer must deliver. The following figure shows a sample process.
The first draft focuses on where information goes and how it should be presented. When writing the first draft, the writer should focus on these tasks:
Determine organization. Fill out outlines from the documentation plan, making adjustments when necessary. Work with other writers and the editor to define the interrelationships among the manuals.
Ascertain places where technical information is missing or incomplete, and alert engineers and the other writers.
Develop thematically unified examples (a scenario) if needed.
Identify terminology issues, and raise them for discussion and resolution.
Develop an approach to the audience defined in the documentation plan, and develop the voice appropriate for that audience.
Develop ideas for art and screen illustrations, and compile a preliminary list of figures.
The second draft should be as complete as the state of the software and the specifications permit. It should be fully illustrated. The writing should be polished.
In the writing of the second draft, the writer should focus on these tasks:
Incorporate edits and comments from reviewers of the first draft.
Revise for clarity and consistency of voice and terminology.
Fill in the technical gaps from the first draft as information becomes available.
Make sure that all terminology and usage decisions made since the first draft are reflected.
Compile a list of index entries, and begin to develop main entries, subentries, and cross-references.
Arrange for a validity test (or perform each procedure yourself) for all chapters to ensure technical accuracy and completeness.
Complete assembly of screen illustrations, and incorporate other types of illustrations.
An ideal editorial cycle includes:
Developmental edit—. A review of structure and organization at the first-draft stage
Copy edit—. A review of readability and style at the second-draft stage
Proofreading—. A final review prior to production
As your company’s publications needs become greater and your publications staff begins dealing with more projects, you will probably want to develop a company style guide. This guide should cover editorial and writing guidelines specific to your publications style and your product line. Besides using Read Me First! as a model, you might want to examine some of the books mentioned in Appendix D.
For more information on working with an editor and for checklists describing the different levels of edit, see Chapter 10, “Working With an Editor.”
If your illustration and design needs are minimal, someone on your team, such as a writer or publications manager, might be able to handle graphics design and illustration coordination. However, as your needs increase, you should consider adding a production coordinator to your staff. This person can coordinate with outside vendors, contract for illustration and graphics design help, or hire permanent staff in this area when necessary.
Processes for dealing with illustrations vary depending on the type of illustrations, the availability of compatible screen capture software, your staffing (in-house or contractors), and your budget.
If screen capture software is available for the operating system you are running, the writer is usually responsible for capturing the screen illustrations. The writer is the one most familiar with what the screen should illustrate and with the software being documented and so can more efficiently set up the screen appropriately. However, you might want to send these illustrations to an illustrator to be “cleaned up” for the best final reproduction quality.
Concept illustrations, on the other hand, usually benefit from having an illustrator render them. Not all writers are gifted artistically, and the time spent producing art is time not spent writing. Illustrators are also more familiar with the “language” of illustrations and can usually produce a more professional concept illustration.
The writer, illustrator, and editor should meet periodically to discuss rough sketches and specifications for illustrations.
A preliminary list of illustrations required for the project is produced by all the writers. (For a sample illustration request form and art tracking form, see Appendix B.) The writers periodically review the illustrations for their specific books with the illustrator until both are satisfied with the final art.
The graphics design for your documentation set might already be established or might be standard for each book or online component. However, you might need a graphics design plan if you are adding new types of components to your documentation set or if you have a new product line for which you want a different look. The following figure illustrates the graphic design process.
First graphics concept meeting. The writers, editor, and graphics designer should hold an initial meeting to identify and discuss product concepts that could best be conveyed through graphics, page layout, and other documentation design issues. The result of this meeting is a graphics design direction for the project. A graphics designer can often also help in designing online tutorials or other online documentation.
Second graphics concept meeting. A second graphics concept meeting is held to approve the final graphics design. If rework is necessary, the graphics designer either produces another sample for another review or executes the art with the final changes incorporated.
This section explains some of the issues related to the publications team and the reviewers during a technical review process. Remember, thorough technical review is an important contribution to the accuracy and usefulness of your documentation. Unfortunately, this concept is sometimes difficult to convey to other groups. This section provides information on how to promote and conduct a technical review.
Make sure that you provide details about the technical review, including its schedule, in your documentation plan or during planning meetings. Emphasize the importance of having accurate documentation that is thoroughly reviewed and tested. Point out the advantages to the whole company in saved support costs, a good reputation, and favorable industry reviews.
Make sure that the relevant departments allow time for their personnel to review the documentation and that they know the seriousness of the review. For successful completion of a documentation project, the reviewers must be available to conduct reviews and to attend review meetings at the time specified in the documentation plan or the review cover letter. (See the sample review cover letter in Appendix B.)
Once reviewer comments have been returned and evaluated, hold a review meeting. This meeting should help ensure the accuracy of the documentation, resolve conflicts between reviewers, and collect final comments. See “Review Meeting” on page 292.
At the conclusion of the technical review and the review meeting, designated reviewers from each department should “sign off” that the documentation, with the agreed-on changes, meets with their department’s approval.
Comments regarding technical errors in the documentation should be incorporated.
Comments regarding technical completeness should be accepted or rejected depending on the scope and intent of the documentation as specified in the documentation plan or as interpreted by the writer, writing team leader, or manager.
Comments regarding the purpose and scope of the manual, including the intended audience, should be accepted or rejected based on the related material in the documentation plan.
Comments on editorial style, organization, or cosmetic changes should be accepted or rejected based on style and design guidelines.
Participants in the technical review process should ideally already be members of the project team. However, even those outside the project team, such as customer support personnel and testers, might be able to provide valuable feedback.
Departments you might want to have represented, and their review responsibilities, are listed here. You might want to provide this information, modified for your own situation, as part of the documentation plan.
Product Development
The documentation accurately describes the technical aspects of the product.
The text, examples, and illustrations are technically correct.
All technical information specified in the documentation plan is included.
Product Test
The documentation accurately describes the technical aspects of the product.
The text, examples, and illustrations are technically correct.
All technical information specified in the documentation plan is included.
The procedures in all written and online documentation have been performed to ensure technical accuracy and completeness.
Marketing
The documentation describes the product as it is specified in any marketing requirements document.
The documentation is appropriate for the target audience.
Proprietary information or information deemed inappropriate for publication outside the company is not included in the documentation.
Customer Support
The documentation accurately describes the technical aspects of the product.
The procedures in all written and online documentation have been performed to ensure technical accuracy and completeness.
The documentation is appropriate for the target audience.
The documentation includes information about how to obtain technical support.
Usability Testing
The documentation is appropriate for the target audience.
The documentation facilitates users’ successful completion of tasks that the product supports.
The instructional objectives of any tutorial material are met.
Publications Department
The documentation conforms to current department and corporate standards and guidelines.
The documentation is written in accordance with the documentation plan.
The documentation is easy to read, well organized, and easy to use.
The documentation is composed correctly: Tables and figures are clear and easy to read, there are no typographical errors, misspellings, and so on.
Legal
The documentation properly uses all trademark and copyright conventions.
All product names in the documentation are accurate and used correctly.
The review meeting is chaired by the documentation manager or a designated representative. The sign-off reviewers designated in the documentation plan should attend the review meeting. Sign-off reviewers attending the review meeting are responsible for consolidating comments from their area into one copy and for resolving conflicting comments from different reviewers in their area before submission.
The writer or writing team leader should prepare an agenda of comment items. In an ideal situation in which comments have been collected online before the meeting, you can distribute reports that list those comments that have been accepted without discussion, those comments that have been rejected, and those comments that are unresolved. Otherwise, mark on the review copies those comments that are unresolved or rejected.
The agenda for the meeting should include rejected comments that reviewers still want to have considered and unresolved comments.
The chairperson leads a discussion of each item on the agenda. Once the items have been resolved, the sign-off sheet should be distributed for representative signatures.
Often, engineers and others think that their comments regarding organization or writing style should receive as much weight as their comments on technical matters. Keep in mind, and make sure they keep in mind, that you are the expert on publications, just as they are the experts on coding or testing.
If your company does a portion of its business internationally, you might need to localize or internationalize your documentation. Internationalization involves creating a “generic” document that can be easily translated into or used in many languages or cultures, converting any language-specific or culture-specific references into generic ones. Localization involves converting a document that is specific to a language or culture into one that is specific to a different language or culture. See Chapter 7, “Writing for an International Audience,” for more specific details.
Some companies simply translate their documentation into specific languages. Other companies fully internationalize or localize the product and documentation. Although large companies generally have a dedicated department to handle this process, others depend on the publications department.
Internationalization and localization is a large and complicated area that requires some expertise. Decisions about the process that affect publications include the following factors:
How soon the localized versions need to be ready after the native-language product is finished. This schedule is often determined by marketing and sales concerns rather than publications resources.
How changes to the documentation within the product release and in subsequent releases are tracked and passed on to the translators.
How long the translation cycle takes, including review and revisions.
How to handle exchanging documents between different formats, both hardware and software.
How the document is delivered.
For smaller documents, you might want to have all languages in one document. For larger documents, you probably will want separate documents for each language. This decision must also take into account your company’s manufacturing, product kitting, inventory methods, and the number of copies to be printed for each locale.
Producing documentation for online presentation involves different concerns than the considerations for printed paper documentation. This section briefly discusses some issues you need to take into account, but it is by no means comprehensive. See Appendix D for books that deal with this subject in depth.
Many companies are turning to online presentation of their documentation to provide customers with easier access to product documentation, to save on printing and production costs, and to provide searchable linked information. If your company is considering such a move, research presentation and usability issues thoroughly.
See Chapter 4, “Online Writing Style,” for detailed information about considerations for online presentation. The sections below contain summary information intended for publications departments new to online documentation.
Because printed text has existed for hundreds of years, writers and readers instinctively know how to use it. Online text, however, is new and constantly changing. People writing and using online text do not have the combined knowledge that comes from generations of experimentation and example.
Writing style. To design online information, writers must change from the familiar writing style used for printed text to an unfamiliar, sometimes undefined, style used for online presentation. Writers also often have a hard time going back and forth between the two writing styles.
Scheduling. Time must be built into the schedule to allow writers and editors to develop their online writing style, and to transition between the printed and online formats.
Platform-specific versions. Some information providers use a “write once, publish twice” scheme that presents the same documentation online and in print. To most effectively take advantage of the benefits of online publishing, however, writers should write text specifically for that medium.
The following list presents some content issues related to online presentation.
Access. You need to determine how the user will find and retrieve information and what navigation aids you will provide.
Text format. First, you must decide whether to duplicate information in both online and print formats, or whether you will provide some information only online and some only in print. If you choose the latter strategy, you need to decide the appropriate format for each type of information.
One typical strategy is to provide task information or brief explanatory information online, and more in-depth information or background information in print.
Graphics. If you decide to provide graphics in your online documentation, you must decide what format they will be in, how they will be included, and whether they will be linked.
Hyperlinks. Some decisions to be made about hyperlinks include which information should be linked and whether links should be accessed only through text or also through graphics. You might also decide to limit the number of links you want in a given body of information. See Chapter 5, “Constructing Links,” for more detailed information.
Page design. Type size, page size, and page layout work differently online than in print. You must decide whether to optimize your design for online or print presentation or whether to use two separate designs.
The following list presents some management issues related to online presentation.
Scheduling. Designing and planning online documentation is usually more time-consuming than print presentation because of the possibility of linked information and the ramifications of online display.
Authoring tools. Online documentation usually requires a different set of authoring tools than your standard word processing or desktop publishing software. These tools sometimes involve separate products for authoring and for online viewing.
Outside resources. Support from other departments is usually required to a greater extent for online documentation than for print documentation. For example, you need to work more closely with graphic designers, product testers, and the software integration team. When planning your online documentation strategy, make sure that the various groups have agreed to provide these resources.
Delivery mechanism. Will your online documentation be part of the interface (as is usually the case with online help, for example) or the product code? Your deadlines and testing procedures will be affected by this decision.
Integration. How will your documentation be connected to the product? You need to find out how the user will access the online information and how it will be installed and set up.
Testing. Testing online documentation involves both the content of the documentation and the delivery media. Links that the user can click to go rapidly to cross-referenced information, for example, are one of the benefits of many online delivery products. Each link must be tested to make sure that it goes to the appropriate location. If the documentation is being delivered as part of the product, the online documentation must work correctly with the product code. Finally, the medium itself must be tested to make sure that it works on all supported platforms.
Legal. Presenting information online usually means a change in how copyright and trademark issues are handled. Consult with counsel.
Production. If your online documentation will be produced on CD-ROM media, you must determine whether it will be included with the product software or on a separate disc. This can also affect your packaging.
ASCII text. Often, last-minute product changes or additions are documented in a brief online file in ASCII text. Consider drafting some formats for this type of presentation.
Activities associated with the final production of hard-copy documentation are:
Printing
Binding
Packaging
In large companies, a separate production department typically handles these activities. The publications organization simply hands off the final camera-ready copy or electronic files. In smaller organizations, the publications department is responsible for these activities.
This section provides only general information about printing and production processes. See Appendix D for sources of more thorough information on these subjects.
Several factors influence the type of printing and packaging used for documentation.
Audience. Is the documentation aimed at in-house engineers or commercial end users? This might determine your page layout or presentation. Under what conditions will your audience use the product? This might determine whether your books need to lie flat or whether you need to use a sturdier page weight or binding method.
Competitors. How are similar products printed or packaged?
Distribution method. If you sell directly to your customers, packaging can be minimal (for example, an envelope or corrugated box). If you are selling to resellers, you probably want a more professional presentation.
Cost. Your operations or marketing departments will probably include the documentation production cost limit when they set a profit level for the product.
While documents can be reproduced in various ways, the two main printing methods are offset printing and photocopying. If you need fewer than 1000 copies of your manuals, you probably want to use photocopying. For 1000 to 4000 copies, regular sheet-fed offset is usually appropriate. For over 4500 copies, you will probably need to use a printer with a web press (one that uses rolls of paper rather than sheets).
Offset printing provides higher quality than photocopying and might be your only choice if you are using color in illustrations or text or including photographs. Note that if you are producing camera-ready copy on a 300-dots per inch (dpi) laser printer, offset printing will not increase the quality of the output.
Offset printing requires a larger print quantity to be cost effective. Ordering a larger quantity just to take advantage of the lower price is usually not a good strategy, though, because you might be left with many copies of outdated manuals. Costs for offset printing are also influenced by other factors, including the use of color, the size of the page (influencing how much trimming is needed), and the type of paper and ink used.
Photocopying produces lower-quality output than offset printing, but it is more cost effective for smaller quantities. Other costs for photocopying might include special handling if you are using an odd size of paper or special paper. Many photocopying machines today can provide rudimentary binding as well as photocopying.
Several types of binding are generally available. The most common binding types are:
Three-ring binders
Wire-o
Perfect
Saddle-stitch
Consider the following factors when determining the binding method you use:
Page size and number of pages
Need for update insertions
Frequency of users’ access and the environment in which the book will be used
Cost
Customer preference
Three-ring binders hold standard 8.5-inch × 11-inch pages or other industry-standard page sizes. (For a price, you can also arrange for custom-size binders.) A big advantage to binders is that you can easily insert updates, change pages, and tabs. Covers can be slipped into plastic pockets in some binders on the front and spine, a feature that saves binder printing costs. However, three-ring binders take up a lot of room. Users often dislike them because these binders are bulky and awkward to handle, and because the rings can burst or rip pages.
Wire-o binding is much less expensive than three-ring binding, is smaller, and lies flatter. This binding offers much more variety in page size. However, updates are difficult to include and the wire prevents the book title from being printed on the spine. Wraparound covers are the workaround to this problem, but they are not very effective and add cost. Generally, users do not like wraparound covers and often cannot figure out how to use them.
Perfect binding is less expensive than either three-ring or wire-o binding, especially in large quantities. A perfect-bound book usually includes the book title on its spine, making the book easily identifiable on a shelf. The chief complaint about perfect-bound books in the past was that they did not lie flat, but recently developed lay-flat or flex bindings have remedied this problem. You cannot insert updates or change pages into perfect-bound books. Also, large page counts sometimes mean that pages might fall out over time.
The type of packaging you use should be determined in large part by how you sell your products and what your competition provides. If you sell products directly to your customers, you might not need as elaborate a packaging scheme as if you were to sell products through an external commercial vendor, where your package competes with others.
Direct-to-customer packaging could be as simple as a padded envelope or corrugated box.
The type of commercial packaging you choose could be influenced by several factors:
The packaging your competitors produce and, therefore, the packaging that customers expect.
The number of different pieces delivered. For example, do you have several disks, several manuals, a quick reference card, and a warranty card? Or do you have a single disk and a single manual?
Your budget.
If you are new to dealing with commercial packaging, you might want to go through your printer to find a reputable packaging source. You can also go through a broker, who puts together a whole production package, finding and dealing with printing and packaging vendors, for a fee.
When you find a packaging vendor, be sure to have the vendor produce prototypes of several packaging designs, and ask the pros and cons of each. You will probably have to provide the page counts for your manuals, and the number and type of other components in the package, before a realistic prototype can be produced.
The best way to find a reputable printer or production broker is to ask people in your geographic area and industry. Ask printers or brokers about their experience with your type of product or about other jobs they have done for people in similar industries.
If your printing and packaging needs are relatively simple, you can probably use a printer who has less experience with your particular product area. However, you will be expected to provide the printer with camera-ready copy and all the information needed for the job.
If your needs are somewhat complex or you have little experience in this area, you will probably need to spend time finding a vendor who is right for you. Experienced printers can provide you with professional advice and samples. They can also explain the pros and cons of various printing methods, paper, ink, and so on. But you have to ask! Larger printers often have account representatives who can offer suggestions and get answers for you if the size of your account merits attention.
If you suspect your printing or packaging needs are very complex or you do not have either the expertise or the staff to investigate vendors, you might want to find a broker. Brokers quote a fee for your whole job and take on the responsibility of finding and dealing with vendors, procuring packaging samples, and so on.
After the documentation is delivered to production, your work is not done. You should have a plan in place to deal with last-minute product changes or inaccuracies in the documentation. Also, if the product documentation is likely to be revised, you should collect and maintain information that will help with the next version.
Despite your best efforts, you might discover technical inaccuracies after the documentation is produced, either from omissions or from changes to the product. Therefore, allocations of monetary and staff resources to the project must continue even after the date the final documentation is delivered to production.
Typical ways to correct documentation inaccuracies include the following strategies:
Online files on the product disks. These files can cover documentation inaccuracies and last-minute product revisions.
Replacement pages. Errors in limited locations in printed manuals can be corrected through replacement pages that are inserted individually by users. These generally ship with the product and are accompanied by a card or insert listing all replacement pages.
Documentation update package. A last-minute change to the product that has ramifications throughout the documentation might require too many change pages to make replacement pages feasible. In this case, you might want to include a documentation update package, which explains the exact changes that need to be made to specific pages, including the paragraph and line location and the information to be added or deleted. However, this solution should be a last resort.
Note
Note — If your company sells directly to customers rather than through a third-party commercial distributor, you can issue change pages or update packages through your distribution channel or sales staff even after the product ships.
Make sure that customer support, marketing, localization, and sales personnel know about the inaccuracies and the steps taken to correct them.
Once a product has shipped, your first impulse might be to try to forget about it as soon as possible. However, your job will only be more difficult when you have to revise the documentation for the next version. Some of the information you might want to save or document about a project includes:
The location of online documentation files. Delete irrelevant files such as earlier versions of text or graphics. You might want to establish a central archive where final files are kept.
While the details are still fresh in your mind, conduct a post-mortem meeting with the documentation team and write down a brief project review. Document anything that might be helpful, for example:
Processes that didn’t work as anticipated or could be modified to work better.
Controversies that arose. Even if they were resolved, having a record of each controversy could prove useful later.
Issues that affected the schedule and might recur during the next cycle.
Subject matter experts or other helpful project team members who were not official reviewers or project team members.
Technical review comments from all official reviewers.
Edits or review comments that you did not have time to incorporate for this version, but that should appear in a future version.
Product information that you did not have time to incorporate for this version, but that should appear in a future version.
[1] Table and description from JoAnn T. Hackos, Managing Your Documentation Projects (New York: John Wiley & Sons, 1994), pp. 47–48. Used with permission.
[2] The material in this section is based on information from Janice C. Redish, “Adding Value as a Professional Technical Communicator,” Technical Communication 42:1 (1995), pp. 26–39. Used with permission.
[3] L. Fredrickson and J. Lasecke, “Planning for Factors that Affect Project Cost” Proceedings of the 41st International Technical Communication Conference (Arlington, VA: Society for Technical Communication, 1994), pp. 357–359.