John’s Note: This article was originally written in 1999. The future is here now…
By John Hewitt
I have a fairly large library of technical manuals. They cover topics such as application programming, web development, networking, and database development. Some of the books are well written and useful; others are of little or no use. Out of all my technical manuals, I have only read about five cover to cover.
I have a supplemental book on FrontPage 2000 that spans 976 pages. It is a good book on the application, but I don’t have time to read it all, and I don’t think I would read it all if I did have the time. There are too many sections that I already know or feel I know, and too many sections that I will probably never use. Still, all 976 pages sit before me and each page costs the publisher money to produce whether I read it or not. That cost, of course, gets passed on to me, and to everyone who buys a book like it. Trees were cut down to make this book. I’m not a serious environmentalist, but it seems like a waste to me nonetheless. Beyond having parts that I don’t need or already know, this book is also inaccurate. I have twice tried instructions in the book that have not produced the promised result, despite my having followed the instructions to the letter.
Because I am a technical writer, I understand that inaccuracies are not necessarily the fault of the writer, or even the editor. This book was produced before the final version of the software came out. It had to be. If the publishers had waited for the final version, before they committed ink to the page, the book would have hit the stores long after the software, and the publishers would have missed out on the initial purchases made by people who wanted to learn the product.
Microsoft, the company behind FrontPage 2000, was under even greater constraints than the publisher of this book. Microsoft’s documentation had to ship with the software, which means that their book had to be produced in time to be packaged with the software. This could take a well over month from their publication-time. I have worked for companies in which I have had to produce completed books before there was completed product code. Microsoft might have had the advantage of quicker access to the final copy than the publisher of a supplemental book, but chances are just as high that they didn’t. In addition, Microsoft’s books also contain material that I will never need, just as the 976-page book does.
For any complex product, the documentation is rarely going to be perfect. There are numerous reasons: product imperfection, rushed schedules, the inability of programmers to convey ideas to writers, the inability of writers to convey ideas to readers, and the tough decisions about who you aim the documentation at and what features you choose to focus on. How do you satisfy both the beginning and the advanced reader? How do you satisfy people who use a product for different purposes? Not all of these problems can be easily solved, but a step in the right direction is a process that I call living documentation.
Living documentation is documentation that does not cease to be developed until the product ceases to develop. Living documentation can be produced at any time in multiple formats. The book, web pages and online help would continue to be developed as long as that development either solves inaccuracy or increases product usability and customer satisfaction. Every software patch would result in a change to the documentation. That change would not await the next product release, but instead would be added to the documentation immediately, producing new versions of the book that would be available for distribution from that point on. The changes would also be incorporated into online help patches that could be downloaded automatically by the application or on demand by the user.
Customer input would also contribute to updated manuals. Through online assistants and other data gathering tools, companies can now track their customer’s greatest needs and problems, and react to those needs quickly with solutions that will improve the quality of their documentation and the customer’s satisfaction.
Living documents will require more work than the current system, but for the most part, the infrastructure is already in place. Most companies already modify documentation to adjust for errors, complaints and suggestions. They simply need to make their changes available to customers in a more timely fashion. In addition, because companies can track customer questions and inquiries through the web, it will be increasingly easy identify confusing or inadequate parts of the documentation even before an actual complaint has been documented, and solve those problems as well.
- Living documents will take the following forms, at least until better technology comes along:
Online books in formats such as PDF that the customer can download and print if they prefer printed versions of the book. These books will also be available as print-on-demand books through major booksellers.
- In depth help pages online that are more than revamped versions of the book, but are also focused on problem solving and customer education.
- Application-based online help patches that are available for download whenever the documentation changes.
I believe that the Internet has granted us an opportunity to add flexibility to our documentation. Many companies are already taking advantage of this flexibility. An example of this is the PC Modem online assistant at CompUSA, which takes advantage of its customer help system by leveraging every customer problem it has solved before to create a comprehensive online question and answer service. Another example is About.com, which has created a business out of providing help on specific topics such as databases. Their approach is to put a real person behind the help, someone people can ask questions of if they can’t find what they are looking for through the links. Another site with a similar approach is www.learn2.com, which provides answers to people’s “how do I?” questions.
In addition, booksellers such as Barnes and Noble are teaming up with other companies such as iUniverse and lulu to produce print-on-demand books that you’ll be able to buy online or at any of their bookstores. These books will be available in both electronic and print formats, and will only be produced when ordered. This will both eliminate the high cost of advance print runs and make it possible to update a book almost instantaneously to correct errors or allow for new information.
All of these sites and services are useful in their own ways, and are constantly updated, but in my opinion they are rudimentary in comparison to what will be happening over the next few years. In my opinion, living documentation is going to have explosive growth over the next five years, and companies that fail to embrace the concept of living documentation will be at a major disadvantage. We live in a time when it is easy to comparison shop for just about anything. Customers will know upfront whether a company’s documentation is a selling point or a reason to look elsewhere.