How Do You Write Technically?

Sometimes it's like putting the pieces of a puzzle together. When I am preparing to write a technical document these are the high-level steps I take in putting it together.

  1. Collect information
  2. Read and understand the information
  3. Interview engineers and architects for explanations
  4. Decide which information is needed by the customer
  5. Write the document using the relevant information
  6. Send out document for review (usually 2 rounds)
  7. Integrate comments
  8. Publish document

So let's take this process and put it to work.

1. I was given a relatively simple engineering document to turn into an article for OpenSSO.

2/3. I read the document and found a term I didn't understand so I asked the engineer what it was. Turns out this was an acronym for a proprietary form of communication.

4. The fact that it was proprietary made this decision for me. I couldn't write about it...

5. ... so I had to write around it.

6-8. I sent the document out for review, received comments back, integrated those comments and published the paper.

The one thing I really wanted to make clear regarding steps 2 and 3 is this: when a technical writer asks a question, it shouldn't be answered, "You don't need to know that." Part of a technical writer's job is to understand the content first and write about it second. Understanding the content means all of it. Only after understanding every detail and/or nuance can the writer then edit it back and decide what the user needs to know. There are circumstances (such as the one above) where the writer's hands are tied concerning content but we still need to know it all first. Only then can we decide what is extraneous. Maybe that's why I find this job so fascinating - I get to be a know-it-all.

And something else I know all about - The 5th Dimension. This seminal, harmonic pop group scaled the heights of the charts in the late 60s/early 70s with hits like Up, Up and Away, Aquarius/Let the Sunshine In and (Last Night) I Didn't Get to Sleep At All. The video below is a cover they recorded early in their career, Go Where You Wanna Go, which peaked at number 16 on the Billboard charts. (The song was written by John Phillips and originally sung by the Mamas and the Papas.) Check out those fashions and syncopated dance moves. Billy Davis, Jr., Florence LaRue, Lamonte McLemore, Marilyn McCoo, and Ron Towson were the bomb before the word even existed. And my parents took me to see them in Carnegie Hall! Yeah man, that's hip.

Comments:

Post a Comment:
Comments are closed for this entry.
About

docteger

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today