Software Documentation

Lesson 1: What is Technical Writing?

What is technical writing? The obvious answer to this question is any writing about technical subject matter, but that isn't the correct answer. Another glib answer is the writing of computer manuals but that too isn't quite right (although computer documentation is a very large subset of technical writing). I've seen the term "technical writing" defined as "any writing designed to aid the reader in the completion of a specific task or process". That too is correct but is so general as to be practically meaningless.

Technical writing is really a cross of all of these things: writing meant to convey technical knowledge and how to apply it in specific situations to a very specific audience. In most cases that technical knowledge is operation of a specific piece of computer software or hardware and that audience is the person trying to use the same.

Types of documentation

Technical writers produce many different types of documents. The most visible documents are product manuals, books that accompany products to customers and instruct them on product usage. Online help consisting of a series of short instructional blurbs incorporated into the product itself is also common. Some technical writers never write any product documentation meant for external eyes but rather write product specification documents for internal use within the manufacturing company. Product specification documents are used to formally define what a product will do, its external interfaces (for instance, the type of menus and forms in the case of a graphical software application), and its internal interfaces (the available modes of communication from one part of the product to another; the functions front-end developers can use to access the underlying database in an application, for instance). This course will concentrate on software product manuals and online help but the material discussed will generally also apply to other documents created by technical writers.