Technical Writing

Lesson 2: What a Technical Writer Does

Writing Example: Rewriting a Specification

Most of the time you will find that you write from specifications of the product, software or process furnished by design engineers. Most of the time also, you will need to contact the engineers or programmers to clarify what they exactly meant in the "geekspeak" that constitutes much of their supporting documentation.

To give you a taste of how technical writers transform highly technical language into documentation that is readable and actually helpful to the user, I offer the following example.

Below is a sample of an actual specification relating to the software panel of an application intended for an oscilloscope. Following the specification is an example of how the technical writer rewrote much of this description in creating the relevant part of the manual. The writer had to interview the engineer responsible for this section of the specification to clarify much of the verbiage. Note that the manual had some illustrations (impossible to reproduce here) of the panel to help the user view the processes involved in accomplishing the operations mentioned. Much of the special formatting in the manual has been lost also.

The following is the specification:

Description of Panel

Input sources: This component consists of input sources that user can select for any measurement. Signal can be either differential or single ended.

Measurement Tabbed Pane: All measurements have been categorized into five categories. To support this Measurement tabbed pane has five tabs. Clock Tab: This category consists Clock based measurements namely Clock Frequency, Clock Period, Cycle-Cycle, N-Cycle, Positive Cycle-Cycle Duty.

Two input sources available for this category are Clock and Clock_Bar where inability of Clock_Bar signal depends on differential toggle button’s state.

Clk-Data Tab: This category consists Clock to Data based measurements namely Setup Time, Hold Time and Clock-Out. Three input sources available for this category are Clock, Clock_Bar where inability of Clock_Bar signal depends on differential toggle button’s state and third one is Data.

Data Tab: This category consists Data based measurements namely Data Frequency, Data Period, Data TIE and Data PLL TIE. One input source available for this category is Data. General Tab: This category consists General measurements namely Rise Time, Fall Time, Positive Width, Negative Width, High Time, Low Time, Skew and Duty Cycle Error. Two input sources available for this category are Source and Skew.

The following is an extract of the section of the user application manual relating to parts of the above specification:

Configuring a Measurement

Many measurements require configuration. To access the Configure Measurements menu, go to the Measurements menu in the menu bar (illustration) and choose Configure> Measurements.

See Also
Clock Edge Option on page 26
Data Edge Option on page 27

Please Note: The following measurements do not have configuration options:

• General area: Rise Time, Fall Time, Positive Width, Negative Width, High Time and Low Time
• Clock area: Positive Cy-Cy Duty, and Negative Cy-Cy Duty
• Data area: Data Frequency and Data Period

In the Measurements: Configure menu, the following message appears on the screen when you select any of the above measurements: "No configuration parameters available for current selection."

Configure: Measurement Menus

Clock Edge Option

The Clock Edge option defines which edge of the clock input is used to calculate statistics of the following clock-based measurements:

• Frequency
• Period
• Cycle-Cycle
• Positive Duty Cycle
• Negative Duty Cycle

This was just a brief comparison of a complex specification and the actual user documentation written by the tech writer. Do not be discouraged if you found the engineer's specification confusing. Frankly most of them are like that, but you get used to deciphering and reading between the lines as you gain experience.

The example also illustrates the importance of consulting with the engineers or other designers in order to ascertain what they truly mean. Remember, you may not have the technical expertise of the engineer, but you are most certainly the expert on communication. In fact, some enterprises call technical communicators, "information engineers."

Recommended ReadingThe Complete Idiot's Guide To Technical Writing, Pages 180-181; review pp50-59

  1  2  3  4  5