I’ve written three book proposals.
I’ve never written a book.
In one case, though, I actually wrote a sample chapter. It was for a book I called, The Accidental Technical Writer: Delivering Documentation That People Will Actually Use. The idea was to meld my 8 years of technical writing experience with my 8 years of interface/interaction design, information architecture, user research…you know, the other parts of user experience.
I thought that too many people have to deliver procedural documentation (the “how to” stuff, often called “user doc” or “the user manual” or such), systems documentation (how does the system work), or other written deliverables…and they don’t really want to do so. Too, I thought it would be a good book for those product managers riffing through Word just before product launch who need to (and want to) improve the utility and usefulness of the documentation users receive.
But it was not meant to be.
So, for your reading pleasure, I provide the “lost” chapter, intended as the introductory chapter to the book.
So you have to deliver documentation
Writing manuals is a very special and privileged task in a computer company, for in the process of writing them you are forced to go over every detail of the hardware and software the company sells in an attempt to make it understandable and usable to our extremely broad customer base. In the process a conscientious writer will discover nearly every good and bad feature of the system, and can provide valuable feedback to the designers and implementors.
Jef Raskin, “”The Genesis and History of the Macintosh Project,” typed ms., 16 February 1981; annotations by Raskin dated 5 November 1993.
Where’s the technical writing staff? Shouldn’t they be doing the documentation? Wait a minute…we don’t have any technical writers! But the project plans calls for an administrator’s guide and a reference guide and online help…and your manager just sent you an email, tagging you with the task. Now what do you do?
Many developers look on documentation as a bane to their existence. Funny, though how many times developers decry the lack of documentation. Ever had to maintain an application someone else wrote? If there’s no API reference or data type definition document or Javadocs, often it’s virtually impossible to do your work.
If you have to simply read the code, you end up taking longer just to understand what the heck is going on with the application. The longer you take in learning about the approach, the intent, and the design, the longer it takes you to get up to speed.
Documentation also has an impact on collaboration. Imagine a distributed team, where the software designers work in Cleveland, the developers work in Budapest, and the marketing staff is in Berlin. So the better the communication is, the better all these groups can collaborate. Oh, and the users of the product are in Kansas City, Guyaquil, and Mumbai.
Benefits of excellence in documentation
Sure, you could simply take an earlier version of documentation, slap the current product’s version number on it, and deliver it. For that matter, you could take the local phone book, change the covers, and call it your administrator’s guide, for all the good it will do. Yet someone, somewhere suffers.
Instead, working toward better documentation achieves strong benefits. Here’s why you need to think about better documentation.
- Good documentation adds value to the product as well as serves as a marketing tool for the company.
- Clear, concise, and accurate information helps the user perform the task; when this occurs, your readers see that you care about them.
- Staff and management work within preset standards, eliminating the frustration of surprises and last-minute requirements.
- Clear, appropriate documentation acts as an added sales tool that helps differentiate your products from the competition.
- Fewer support calls free up help desk staff to answer more complex, time-consuming calls.
It’s not literature, but it is important
Writing is easy. All you do is stare at a blank sheet of paper until drops of blood form on your forehead. — Gene Fowler
Writing is difficult. Anyone who’s ever had to deliver a report or a white paper or an instruction manual knows that. Just as buying Visual Studio doesn’t make you a developer, buying a copy of Microsoft Word doesn’t make you a writer. Too, simply speaking a language doesn’t mean you can communicate concepts in text well.
At the same time, following some key guidelines helps improve documentation immensely. This book provides these key guidelines.
Using this book won’t make you a great novelist nor a professional, fulltime technical writer. What this book does do is help you overcome writer’s block, organize your approach to documentation, and reduce some of the pain of writing. Too, by focusing on delivering documents people will really use, you can improve your product’s quality, acceptance, and success.