|   Home   |   Careers   |   News & Events   |   Contact us   |

Best Practices

1 - Gain Cooperation from Engineering Cooperation between writers and engineers can make or break a project. When subject-matter experts (SMEs) are unavailable, the writing process is delayed. When SMEs do not return reviews or they return reviews with vague comments, a face-to-face meeting with each SME is necessary. Ensure that SMEs know the following: When to expect the review and schedule time accordingly What sections they are being asked to review How and when you want the reviews returned One process we have found that improves the review return rate is to create a PDF or HTML version of the document and then send an email to the SME with links to the sections you want them to review. This works effectively for command references that tend to be several hundred pages in length, since even the most dedicated SME might be overwhelmed by a 500-page document they find on their chair! 2 - Use Metrics to Determine Schedules Many groups base their schedules on calendar time only and then do what they can in the time available. Accurate writing and production hour estimates can help you staff your project to meet even the most aggressive schedules. It can also help you set realistic schedules with engineering and marketing. At Lasselle-Ramsay we use 3 hours per page for new documents and an average of 1.5 hours per page for updating documentation. Copyediting and formatting the layout are typically 5 to 6 pages per hour each. If a new, 100-page manual is needed for a release, a nine-week schedule is required to produce a quality manual, including review and production cycles. 3 - Reduce the Number of Documents The more documents you have, the more they start to overlap. They also typically duplicate overview information that is needed by all audiences. Consider structuring documents to serve multiple audiences. For example, if a product runs on Windows and Macintosh, two separate manuals may not be needed if the feature set is the same. 4 - Use Electronic Distribution One of the items with the biggest impact on your documentation budget is printing costs. Evaluate the possibility of shipping the installation guide and delivering the support documentation as PDFs on the CD-ROM or over the Internet. Alternately, have your customers fill out a card if they want to receive a hard copy of the documentation. 5 - Implement a Best-Practice Methodology A best-practice methodology sets the expectations between the technical publications group and the other members of the release team. If you don't have a methodology, you might be adding to your development costs with insufficient planning or excessive reviews. Lasselle-Ramsay follows a four-phase methodology, called the four D's: Define, Design, Develop, and Deliver. The Define phase includes estimating the resources, setting the schedule, and performing an audience assessment. The Design phase includes creating a detailed documentation plan, templates, and editorial style guides, and then defining naming conventions. The Develop phase typically includes two or three reviews, copyediting, proofreading, indexing, and final layout. The Deliver phase includes creating the final media (print, PDF, online) and getting the information to the client. 6 - Use a Single-Source Solution Single-source documentation means that you write it once and use it multiple times. The best example of this is to write a user guide in FrameMaker and use WebWorks Professional to convert the information to online help. A one-time investment in a WebWorks template eliminates the need for multiple writers to create the same information for print, online help, and HTML. 7 - Invest in an Audience Assessment Your customers, whether internal or external, determine the level of documentation that is needed for your product or service. An assessment can help you identify the tasks they will be performing and the knowledge they require to be successful. Find out how and where they are using information—in the field, at their desk, or only during installation. 8 - Use the 80/20 Rule for Writing Focus your documentation efforts on the 20 percent of the product that 80 percent of your customers will actually use. By fully documenting those features, you will substantially reduce the number of calls to Customer Service. For example, 100 percent of your users will have to install the product in order to use it. Never skimp on an installation guide, but write only what your customers need to know. Functional specifications and engineering requirements documents are often loaded with all the functionality and capabilities of a feature that is being implemented. The end user usually does not need to know all the details. 9 - Justify Documentation Requests Implement a process for approving additional documentation that includes justifying the expense. If the request is coming from an internal group such as marketing, sales, or field service, ask them how the customers will use it. Show the internal group the costs of creating and maintaining the document for the product life cycle. Hopefully, you have your own numbers (from #2 above). A ballpark number is $300 per page to create the document and $100 per page, per year, to maintain it. For a 200-page document, that would amount to $80,000 the first year and $20,000 each of the following years. A less expensive solution might be to post FAQs or white papers on your company's Web site. 10 - Minimize Rewrites As software release cycles become shorter, writers often begin writing documentation before the code is frozen. This approach requires making assumptions that the product will work as described in the functional specification, and rewrites are the inevitable result. Find out which features are stable or frozen, and write those first; an installation guide can't be written until engineering knows how the product will be installed. Get agreement with engineering on code freeze dates before capturing screen shots. When last-minute changes are made to the GUI, the impact on the quality, budget, and schedule for retaking screen shots is staggering.

About us Solutions Services Success Stories Alliances Best Practices Copyright 2004, Lasselle-Ramsay