Focus Forward - An e-newsletter published by Tim Rosa Associates, LLC March-April, 2007 Vol. 4, No. 2 When is the Right Time to Start Technical Documentation? -------------------------------------------------------------------------------- Welcome to Focus Forward, the e-newsletter of Tim Rosa Associates (http://www.timrosaassociates.com/index.html). Based on feedback from subscribers, we’ve gone to a bi-monthly (occurring every two months) frequency. Remember that past issues (http://www.timrosaassociates.com/L1_newsletter.html) can be found on our website. If you find this newsletter worthwhile, I hope you’ll forward it along to colleagues by clicking this Forward email link (http://ui.constantcontact.com/sa /fwtf.jsp?m=1011204234254&ea=trosa@timrosaassociates.com&a=1101216919541&id= preview). If you do not want to receive Focus Forward, click SafeUnSubscribe(TM) at the bottom of this newsletter, and we shall never bother you again. -------------------------------------------------------------------------------- *** When is the Right Time to Start Technical Documentation? *** Regardless of the size of a client’s company or the scale of their engineering effort, I hear the same questions when discussing technical documentation project with our clients and prospects: - When is the right time to get started with the technical documentation? - Can it be written from specs or prototypes, or does the working product need to be ready? - How do we determine which pieces are needed in the full suite of documents, and how do we prioritize them? WHAT IS THE VALUE OF TECHNICAL DOCUMENTATION? We help technology companies of all sizes—from small start-ups to the Global 500—in their efforts to create high-value, high-quality technical documentation. With solid planning and excellence in execution, technical documentation can reinforce the value of the product, reduce customer support calls, improve customer satisfaction, and contribute to the bottom line. No matter how advanced your product may be, focused technical documentation makes a real difference in the product’s long-term success. BRIDGING SOFTWARE DEVELOPMENT AND DOCUMENTATION Developing hardware and software is complex and requires a disciplined methodology. Similarly, better technical documentation is created using a process which parallels the process of creating software and hardware. Technology companies choose from a variety of software development methodologies including: - Waterfall, incremental or spiral model (http://en.wikipedia.org/wiki/ Software_development_process) that provide an orderly structure - Object-oriented (http://www.oopweb.com/) and graphical programming (http://www.oopweb.com/) techniques - The Agile Alliance’s (http://www.agilealliance.org/) timebox (iteration) method - The Capability Maturity Model (CMM - http://www.sei.cmu.edu/cmm/) developed at Carnegie Mellon Institute - International standards such as ISO/IEC 12207 (http://www.12207.com/) and ISO/IEC 15504 (Software Process Improvement Capability Determination – http://www.isospice.com/) Companies can model the development of their technical documentation on one of these methodologies. We developed the 3-D Process (http://www.timrosaassociates.com/L2_3dprocess.html) at Tim Rosa Associates over the course of thousands of successful projects. Creating technical documentation in a way that closely follows your company’s software development methodology, results in fewer software defects (“bugs”), enables shorter development and documentation timelines, creates better value for customers, avoids steps that waste time, and makes for more satisfied employees. GETTING STARTED WITH DOCUMENTATION Deciding on when to get started with documentation requires an understanding of the various milestones of your product development process. For example, key milestones might include Alpha, Beta, First Customer Ship (FCS), and General Availability (GA). For each of these development milestones, you need to work with Engineering, Product Management, Technical Support, and Sales to answer key questions from your customers’ and your company’s perspective. From the Customers’ Perspective - Are customers expecting to see documentation at every development milestone? - Do they need to install the product or is it ready to use when delivered? - Once installation is complete, do customers need to configure the product for their own use? - Do customers need to perform any integration or customization steps in coordination with other parties to deploy a total solution? - Can customers install/use the product without documentation or other user assistance (help files, wizards, Flash demos, training videos)? - Will the product operate in largely the same manner in Alpha or Beta phases as planned for FCS and GA releases—for example, will the user interface undergo dramatic changes at each milestone? From the Company Perspective - What are the costs to the company (financial, human, and reputation) if customers cannot install and configure the product at each milestone? - If documentation is inaccurate, limited or otherwise unavailable, who will help customers if they need it—Technical Support, Software Engineering, channel partners? - Have specific expectations been set (by Sales, Marketing Communications, Customer Service) with customers about features and functionality that will be delivered at each milestone? - If your company does not provide any documentation to customers, how do you expect they will they learn how to use your product? - If you do provide documentation at each milestone, how will you solicit, collect and integrate feedback into the next release of the material? - Can your company plan either to avoid or exploit dramatic changes in the user interface at each milestone? STAGING DOCUMENTATION AS RISK MANAGEMENT The answers to these and other questions will help you develop the appropriate documentation plan. As any veteran of the product development process knows, however, any approach brings with it some degree of risk. In working with our clients for over 15 years, we’ve found a number of “best practices” for technical documentation to help minimize risk. 1. Start early. If your company writes user requirements, specifications (functional, design, user), or working prototypes, share these with the doc team, even if they aren’t complete. This provides a basic understanding of what engineering is working on before the formal doc process begins. If there isn’t much in the way of written materials, have product management do a formal presentation to the doc team. This can be done in person, NetMeeting, webcast, and/or conference call. 2. Keep the doc team informed. Create a system for continually assessing the health of the documentation effort. Is the doc team staying current with development—are they going too fast, too slow, or just right? How often does the doc team “sync up” with the project team? What is the risk to the plan if they fall behind? 3. Understand expectations. Discuss expectations about completeness and quality with both internal and external customers in advance. Some customers might be happy with a Beta document that is 50% complete, while others want to see 100% of the features described, even if only at a high level. The sales team may need technical documentation to help them “sell” wary participants on being part of the beta program. The key is identifying both the depth and breadth of information that may be needed. 4. Prioritize risk. Resources are not limitless. Consider the risks associated with not including a document at a particular milestone. If problems occur, is your organization equipped to address them at this stage in development (for example, has Customer Support been trained at this stage)? If the risk is excessive, restructure the project to mitigate risk and deliver the document customers expect. 5. Under promise and over deliver. If you’ve been successful in promoting the business value of documentation to reduce costs and enhance the customer experience, you’ll need to follow through. Be sure to deliver the quality that you’ve promised on time and on budget. If you establish a deadline for the documentation, hit it. Customers know if you miss a deadline and they won’t forget it. BOTTOM LINE Tim Rosa Associates (http://www.timrosaassociates.com/index.html) started in 1991 as a “tech doc shop.” Since that time, we have expanded our service offerings to include training, marketing communications, regulatory writing, and validation documentation for technology, healthcare, and financial services companies worldwide. With a team of more than 100 senior-level writers, editors, information architects, copywriters, graphic designers, and technical illustrators, we’ve conquered countless technical documentation challenges. It’s hard to stump us. If you need fresh ideas to help you create technical documentation, online help, and other content to enhance the experience of your customers, email me at trosa@timrosaassociates.com. -------------------------------------------------------------------------------- *** For More Information *** - Send me your feedback (trosa@timrosaassociates.com) - Read about our services (http://www.timrosaassociates.com/L1_services.html) - Read about Tim Rosa Associates (http://www.timrosaassociates.com/L1_aboutus.html) - Contact us (http://www.timrosaassociates.com/L1_aboutus.html) -------------------------------------------------------------------------------- Thanks for reading, Tim Rosa Founder and Manager Tim Rosa Associates, LLC Copyright © 2007 Tim Rosa Associates, LLC. All rights reserved.