Technical Writing in a Nutshell

Getting Up to Speed

A successful technical documentation project entails swiftly learning the subject matter in order to produce the desired content within the defined time frame, while minimizing the impact on SME (subject matter expert) and client resources.

While some companies have well-staffed documentation departments, others recognize the need for documentation only at the last minute, which can result in a rushed project. A valuable technical writer must therefore possess a tool chest of skills, shortcuts and tricks to speed the work. Some examples:

• You should be an expert MS Word user and know as many keyboard shortcuts as you can
• Being an expert Visio user will sometimes, by itself, land you a project
• Also be an expert Acrobat user
• Knowing HTML can be a great help
• Quickly and professionally editing images and screenshots is essential (I like SnagIt but if serious editing skills are needed, then it can only be Photoshop)
• Using clever utilities to speed time-consuming tasks is also essential. A couple of my favorites are Bulk Rename Utility and Sendto X (a Windows 95 PowerToy that still works in later Windows versions and which I've carried with me since the "old days")
• Always be thinking about how to automate tasks, and do your research on the best tools for the job

Learning the subject matter you will be documenting, as well as any ancillary required tools, can be a daunting task. While clients do anticipate this learning curve, several key things will speed this step - get your eyes on the application, even if it's an in-progress development copy. Study the business requirements and developer notes so you can distinguish where it's going from its current state. Get onto the developer's tracking platform - read the releases, scrum notes and bugs reports. If the application or system is in use, sit with one or more users as they go through their day to day tasks. Be as unobtrusive as you can, pay attention and take notes. Copious notes.

Good Documentation

The qualities of good documentation are easily understandable wording, predictable instructions and useful visual aids. Unless space is at a premium, screen shots with good labels that orient the reader are essential. Think out your image captures thoroughly, and don't forget that aesthetics count.

The acid test of good documentation is whether a completely uninitiated end-user can smoothly and successfully execute the actions by following your documentation. A technical writer should always test his documentation on himself first (pretend you know nothing about it), and then find willing subjects to walk through the software or process using your instructions.

Adding Value

Application testing is an inevitable byproduct of software documentation projects. Why? In order to ensure that the user manual or online help matches the software function (and that the software in turn matches the business requirements).

The technical writer will often become thoroughly versed on the application functionality and finds himself being an ad hoc software tester. When the business users do not have time to fully test the software (which happens a lot), the technical writer can assume the role of "business-side" expert and become an asset to the developers. In fact, if this is not happening on your software technical writing projects, you should figure out why not. 

Bigger and Better Things

Once you become known as someone who can easily write just about anything, do not be surprised to have people from other departments ask you, either officially or on the down low, to help write or prepare something. It it's something quick you can do it quietly, or show the person how to do it herself. On bigger tasks it's smarter to ask permission of your client manager. Either way, helpfulness counts and you will find that your reputation will grow, As a result the client may ask that your engagement be extended so that you can work on additional projects.

And if your technical writing project experience has accustomed you to software lifecycle and/or IT systems, then your good initiative, management and organizational skills may make you a candidate for project coordinator or even project manager roles.