TECHNICAL WRITING

Technical writing experience is a tricky thing to discuss because “technical writing” has a number of meanings specific to different technical groups, and often one won’t recognize the definitions of another. In the tech-heavy Bay Area, for instance, software technical writers are considered a breed quite distinct from technical writers from other disciplines. That is because writing for software developers often requires a technical understanding or competence in programming languages like C++, Java and SGML, or metalanguages like XML, which are not required in other technical fields (like non-software related scientific research). Technical writers in the software industry even use authoring tools, like FrameMaker and RoboHelp, that are rarely if ever used in other forms of technical writing.

On the other hand, technical writing in a broader sense refers to an educated adherence to a formal and generally accepted set of practices and standards in the presentation of a wide range of technical information. In that sense, it bears some resemblance to “packaging.”

Referencing such bibles as the Chicago Manual of Style, technical writing is a rich, highly codified process for handling the infrastructure of those types of documentation that require the highest standards of clarity and accessibility. On this level, it is the writing itself that is “technical” and obeisant to established ways of handling sentence structure, capitalization, abbreviation, punctuation, bulleted lists, references, and every other aspect of written communications. 

“Communications” is the key word. Effective technical writing communicates the information required by its intended audience in the form best suited to meet that audience's needs. A big part of the technical writer's challenge is gaining an understanding of the audiences he or she serves so information packages are developed in informed ways.

The Society for Technical Communication (STC) defines technical communication as "The process of gathering information from experts and presenting it to an audience in a clear, easily understandable form." In this view, technical writing is a mechanism for transferring knowledge from expert to audience, and the skills required to build that bridge are the currency of all technical writers, whether they be developing software user guides, technical proposals, procedure manuals, or technical papers.

"Technical writing and editing is an umbrella term for any sort of professional communication. It's the interface between your ideas and the rest of the world." (Wikipedia)

TRAINING PROGRAMS

My introduction to technical writing probably occurred when I joined BayGroup International (then called The Bay Group) in the late 1980s. Though I had more than a dozen years of professional writing experience under my belt at the time, my work at The Bay Group was my first experience with training materials and the notion of “unpacking” information in a manner designed to be procedural.

BayGroup International is a firm that custom develops corporate training programs in negotiation, contention management, and conflict resolution. Their clients are Fortune 100 firms, such as Kodak, Hewlett-Packard, and AT&T. My work there was the stuff of classic technical communications: I interviewed subject matter experts, observed their presentations, and documented what they were doing in classroom materials, including participant learning manuals, leader guides, and training exercises. I also worked with experts in behavior analysis to develop instruments for profiling the behaviors of class participants, and developed reports used to customize their individual learning experiences. The documentation was initially developed in PageMaker, but the Microsoft office package was growing in strength at the time and we eventually redeveloped everything in Word.

Among the work I performed there was involvement in the development of their Contention Management product, which gave me experience with the entire product development cycle from concept through final delivery.

SOFTWARE MANUALS

In 1998 I completed a 200-hour certification course in technical writing offered by the Webster Institute of Technology, which was headquartered in San Francisco. (The firm now goes under the banner Webster Associates, has dropped their training division, and is now headquartered out of Santa Cruz. They place technical writers.) The course was entirely geared to technical writing for the software/hardware industries, and the training was focused heavily on the use of FrameMaker, for developing manuals, and RoboHelp for developing on-line help systems. The firm also trained in interviewing technique.

Before completing the course, I was hired as a contractor by IKOS, which was then a Cupertino (now San Jose) based software/hardware firm offering emulation tools for testing chip design. It was a hard core engineer-to-engineer technical communications assignment, and I worked closely with product managers and programmers to document new releases of two of their products. I also supported their efforts to improve their on-line tutorials. All of the work was done using FrameMaker in a UNIX environment.

PROCEDURE MANUALS

After my IKOS experience I took another contract position developing procedure manuals and on-line help for Legacy Marketing Group, a Petaluma-based operation that develops and handles administration of annuity products sold through major insurance carriers like Transamerica. This again was classic technical writing. I developed manuals for several divisions of the company, interviewing subject matter experts and observing business processes. As the project evolved over two years, we developed help systems using Doc-to-Help, a tool similar to RoboHelp that uses Word as an authoring tool and compiles text for on-line display. I spent a lot of time editing HTML to ensure that the help system displayed properly.

This was an important project for me inasmuch as it involved a complete development cycle, from concept through implementation. Myself and a team of technical writers worked with Legacy executive staff to determine project goals and objectives, with quality assurance staff to identify specific project requirements, and with training staff to outline documentation approaches. We considered a variety of software options to determine what would offer the greatest flexibility during development, and the greatest ease of update and maintenance. We followed a defined product development cycle, guided by an MS-Project schedule, and went through several rounds of testing before unveiling the finished package.