Technical writing

Technical knowledge versus technical communication

technical writing logo

After a brown-bag presentation from a Linux-based technology company recently, a colleague who was an expert in mainframe technology asked a friend who was a UNIX expert, “Did that make sense to you?” The answer was affirmative, but only because the UNIX expert had already done outside study on the subject. Both technicians agreed the presenter obviously understood his subject, but both also agreed that the presentation failed to communicate with its audience.

What went wrong?

Simply stated, the wrong person was selected to make the presentation. A technology guru by definition must know how to communicate with computers, which speak in variables, parameters, arrays, loops and keywords that only programmers and computers can fathom. Programming is a high skill that requires a lot of concentration, but being able to program does not automatically confer skill in explaining to non- or less-technical people how they can use that technology to accomplish their tasks of writing reports, updating web sites or crunching numbers.

Read moreTeaser break marker

How much does size matter?

technical writing logo

Interviewers and job descriptions sometimes make a point of requiring experience with "large" documents, and I always wonder what the underlying concern really is. What, in the mind of the interviewer or person writing the job description, distinguishes "large" documents from "small" ones?

Generating documents of any size requires skill with a word processor, including knowledge of how well the software handles documents that are primarily text as opposed to ones containing numerous graphics. As documents increase in size, however, navigation aids, organization and typographical style become more important.

Large documents inevitably need such items as tables of contents, indexes, cross-references and section breaks and associated headers, footers and pagination. These items can be tricky to use and maintain. Once the need for them is established, however, whether the document is 50 pages or 500 does not matter. The questions here, rather, are whether the technical writer both can determine when these conventions are needed and can implement them.

Read moreTeaser break marker

Technical writing: the step-child of IT?

technical writing logo

In my experience, technical writing alone of all the information technology functions is treated as a luxury. One large company for which I worked, for example, immediately eliminated the technical writing team whenever financial troubles loomed. Technical writing was considered “overhead” that did not directly contribute revenue; therefore, it was expendable.

This attitude has seemed nearly universal, at least in large companies. Only two conditions seem to make documentation a high priority.

1. Regulatory requirements

If a regulation requires documentation, it will be created. A number of people will want to have an imprint on the product. They will want their names listed as contributors, their points of view addressed and their concern for doing things properly noted.

After the document is written and the regulation satisfied, however, it is likely no one will ever read the document or direct anyone to do so, until something goes wrong. Then, the document will become the proof that someone - usually someone in the rank-and-file who is considered expendable - was at fault.

2. Downsizing and cost-cutting

When companies decide to eliminate jobs or lay off or replace personnel, the work those employees handled must be done by someone else. The tasks might be added to the workloads of remaining personnel, or they might be outsourced. In either case, documenting procedures becomes critical. I have even heard of companies penalizing outgoing personnel, via severance packages, who fail to train their replacements.

Read moreTeaser break marker

Managing documents

technical writing logo

Any kind of writing involves multiple drafts of the same document. I think technical writing can be especially challenging, because normally there are several documents in development at the same time, often there are multiple reviewers for each. Some organizations have streamlined collaboration so that one document comes back with all the suggestions.

In my experience, however, most companies' review process is something more than handwritten notes from 15 reviewers but something less than the ideal single draft containing all 15 reviewers' changes. Planning how to handle all those files before the numbers explode can make the project run more smoothly. That attention to organization can also provide a solid base for clients unsure about how to manage documentation once it is created.

Read moreTeaser break marker