Great Technical Writing: How Small Companies Can Create Great User Documents

Overview

Your product needs User Documentation (manuals, instructions, etc), but your small company (20 to 100 employees) has no in-house staff to create that documentation. This article describes how to select and enable your "non-writer" employees to create Great User Documentation. You NEED Great User Documents

Your Product needs Great User Documents (Instruction Manuals, User Guides, Reference Manuals, Instruction Sheets, etc. ):

. Undocumented features become expensive flaws . All products have shortcomings; Great User Documents help your Users around these problems . Providing information beyond the minimum helps reduce technical support costs

Your Users deserve Great User Documents:

. To eliminate jumps in the documentation that the User cannot follow . To understand what the product will do and how it performs . To provide tips and knowledge to provide the best possible User experience

Great User Documentation will reduce support costs, increase User satisfaction, and increase your profit (fewer returns and more positive recommendations).

But You Have No Writing Staff

Yes you do! If you can find employees who are between projects, or want to take on additional responsibilities and acquire new skills, then these can be your writing staff.

However, you may be considering hiring an outside freelance writer. Perhaps that is a good choice. However, let me list some benefits of using in-house non-writers over freelance writers:

. Experience with the company (culture, management, style, physical plant) . Knowledge of the product, market, users . They may know the members of the design and development teams . Already set up with resources in your company (desk, phone, access to information resources) . Will be a resource you can use to upgrade or create new documentation . Will effectively employ someone who is between projects

Selecting Who Will Write

Ask your staff if they would like to write the User Document for a particular product:

. If you have any volunteers, then these are the employees you should consider to become your writers. . If you do not have any volunteers, then you might have to resort to coercion. Perhaps explain the benefits of writing versus other less-attractive busywork (or even temporary layoffs). . If necessary, assign someone or a group to the writing task.

Convincing Your New Writers

. Tell them that you will provide support, training, and time to do the writing. Make sure that you keep your promises. . Tell them that writing skills would benefit their career (communication skills are usually a benefit) . Variety will make their work more interesting . You will try to make this as no-risk as possible . Tell them that the Great User Document that they produce will benefit the product and the company (and them).

If they have other objections to the writing assignment, evaluate their objections, and determine if you have a reasonable argument to overcome their objections. If not, perhaps you had better find someone else for the writing project.

You Can Enable Non-Writers to Write

Most of your employees who have made it through an education system, and have been hired by your company, can probably write. They may be fearful of writing. I believe that if they can think clearly and explain something verbally to someone sitting next to them, then they can write Great User Documents.

To just thrust a writing assignment on the non-writer is unfair and will prove to be unproductive. You need to support the new writer.

How to Support Your New Writers

Training

. They need a complete method for writing. They need guidance on how to start, what tools they should use, and a method for producing great User Documents. . They need an effective organization for the User Document. They need to know what to include in the User Document and how to structure the document . They need an easy way to write the first drafts and how to revise them . They need a way to feel comfortable performing the previously stressful task of writing. Most people remember an adversarial relationship between themselves as writer and their reader (usually a teacher or critic). . They do NOT need grammar lessons. Hire an editor, and if cost-conscious, hire one from a university. See the editing article in the on the site listed in the "Resources" or "About the Author" section of this article.

Support:

. Access to the development and marketing teams; . Use of the development team to evaluate their writing (small chunks); . Access to the product, literature, marketing materials.

Resources:

. Style manual; . Editor; . Time to do a good job

The resource links in the "Resources" or "About the Author" section of this article will help your new writer get going.

Beware of Technical Lures

If your new writers come from your technical areas, they may want to spend time learning writing technology. They do not need it!

My point is not to spend the time learning new tools that might not benefit your company's situation. Let's look at the two popular lures:

1. Fancy Writing Software

Very few professional technical writers would use a word processor to create a large User Document. However, in all likelihood you will NOT be creating a mammoth User Document. Most likely your User Document will be less than 40 pages. A modern word processor (such as Microsoft Word, WordPerfect or Lotus WordPro, all are trademarks) will easily do the task.

2. Content Management System (CMS)

I believe that the documentation industry has incorrectly focused itself on Content Management Systems (CMS's). CMS's are reasonable tools for large companies like Microsoft, IBM, and Toyota who have huge numbers of documents. For smaller companies (like yours), CMS's are a diversion from the real task, which is "how to produce the User Documentation that your product needs and your Users deserve."

Aha! Your new writer might say that by writing in XML or by using a CMS he/she will be able to create the text in one format and easily produce that text in HTML, printed form, or as a PDF (Portable Document Format, used by the Adobe Reader). This is not a valid argument for your situation. Modern word processors have the capability of producing HTML documents, converting their output to PDF, as well as printing.

Another argument is that a CMS will enable writers to re-use content from one product to another. I believe that this argument is not relevant to companies with only a few products. While old-fashioned, a good library system and using cut and paste will suffice for the smaller company.

Instead, Focus On These

Rather than spending time learning new technology that may or may not help your writing project, your writers (in fact, all writers) should be focusing on what is important to the Users of your product. These are:

. Content: The material that you will provide in your User Document . Access to that Content: Enabling your Reader to easily find what he/she needs at the time, and to skip what is not needed

If your new writers do know how to use writing tools such as FrameMaker (tm) or a Content Management System (and one is set up) then of course they should use these tools. But everyone should remember that the Reader (the User of your product) only sees the content via the accessibility to that content. Don't let the technology get in the way of helping your Reader.

The Bottom Line

Most literate people, with reasonable support and resources, can be guided to create effective User Documentation. A good place to find resources is listed in the "Resources" or the "About the Author" section of this article.