Wednesday, July 22, 2009

G2G

A genre of technical writing that doesn't get a lot of attention is Geek-to-Geek (G2G). In that genre, highly technical people are communicating to other highly technical people. Most of the discussions in technical communication deal with transferring technical knowledge from experts to the average Joe.

Professional technical communicators need to be very careful when inserting themselves into G2G scenarios. Some examples:
  • I had an intern once work on a specification document our engineering group had written so that customer IT folks could configure their applications to exchange data with our application. She took out the word "argument" everywhere it occurred because it sounded confrontational.
  • I had a layout/graphics designer make a training manual I had written more "user friendly" by changing "120-volt (AC) solenoids" to "120-volt air conditioned solenoids."
  • I was reviewing a document a software developer had written that was to be sent to other software developers in the company and found his excessive use of multi-layered indents to be distracting. I was just about to comment on it when another developer looked over my shoulder and said, "Cool, he's using FORTRAN formatting rules; that makes it so much easier for me to follow."
By no means am I saying that professional technical communicators have no role to play in G2G, but I do think our role changes a bit, and I think some of the rules we normally follow need to be modified.

I was recently involved in a G2G situation, and I noticed some differences between that genre and G2J (Geek-to-Joe). A developer in my company had written some documentation about how to use an open standard reporting tool to issue reports from one of our products. The readers would be developers who worked for our customers. Some differences:
  • Technical writers (uh, me) like to write in generalities; geeks like specifics. We talk about how to change parameters, they describe how to change a specific parameter.
  • Geeks want to show how things work--often describing what goes on under the covers; technical writers don't feel they need to prove the procedure does what we say it does, or even explain why it does. For example, in his discussion of parameters, the developer told the reader to run a specific report, then had the reader change a specific parameter, and then run the report again to see the effect.
Seeing how the developer wanted the reader to run a report, make a change, and run the report again reminded me of an experience I had years ago when I was a trainer at Nordson Corporation. Nordson is a company that makes glue applicators for packaging equipment (a hardware environment completely on the opposite end of the spectrum from the software world I now live in, but geeky none-the-less). We had a new product that glued cartons with a "sift-proof" seal--very useful if you're packaging powdered products like laundry detergent. The only problem was that we had only one field technician who seemed to be able to install one of these things correctly. So they sent me into the field with him to learn what he knew and to pass that on through training to the other technicians.

We got on site and the technician got the glue guns and sealing bracket all bolted on. He showed me a bolt that affected alignment of the sealing surfaces and explained: "Here's how I adjust this," and he turned it fully clockwise and ran a carton. The resultant sealing job looked awful. He then turned it fully counter-clockwise and ran a second carton. It too looked awful, but in a different way. He smiled and said, "See, now I know what effect it has, so I can now adjust it." Well he went on in this way through about three other alignment controls and in half an hour had this machine cranking out perfectly sealed cartons.

Hard to put into a training module, but a good insight into how geeks think and work.

Some things to consider when intervening in G2G:
  • Geeks need to know underlying principles that will let them predict cause and effect.
  • Geeks like examples.
Places we can add value:
  • We know how to write instructions.
  • We know our company's legal and style requirements.
  • We know how to produce and distribute documentation efficiently.
It might feel a little secretarial, in so far as we should give the SME a little more leeway to dictate what information is important, but we still add a lot of value when we help make these G2G documents more "customer-facing."

But don't just roll over and play dead--for example, I took out the parts where we were telling users to run reports to see that changing the parameter really did affect the report--but in G2G, the geeky writer probably understands the geeky user better than we do. Be aware of that and try not to break what could be a perfectly clear explanation by recrafting it for the average Joe, who will never read it.

6 comments:

info said...

G2G - love that one :) I can just confirm your post: During a survey we found out that our geek users do not use our help because it is too G2J and their answers are more likely to be answered in techie blogs or forums.
I think we all must learn not only to see the "oh, where do I click" user but also the "can I also use ahell command here?" user.

Melissa said...

Mike! I love the acronym, and I won't go into how many times I've had to argue with an editor/peer reviewer about how "instantiate an instance" really can't be written differently. --Missy

Margaret said...

Not every "technical" writer can handle the G2G end of the audience spectrum. Technical communicators have to not only evaluate the needs of the specific audience but also evaluate what part of the audience spectrum we can competently address.

Janet S. said...

G2G docs can still use audience analysis by a technical writer. What is important to one geek may or may not be important to another. For example, the geek who develops an API is usually more of an expert in that domain than the geek who calls the API. The receiving geek may need overview concepts that seem "obvious" to the transmitting geek.

ted said...

Ditto Janet. Plus: We "like" generalities because have to. We could hire all the writers in the metropolitan area to cover every value for each parameter, but my VP isn't going to fund it, don't know about yours. Generalizing intelligently is how we make the specifics useful, available and true, which is what they are paying us for. Now: can someone translate that into geek for me?

Michael Hughes said...

Ted, the post is not meant to pit one against the other; just contrast them. To translate into Geek would be "Here's an example of how to set the such and such parameter, the others work the same way." Abstraction is a good thing and we technical writers are good at it. But sometimes, describing everything in a highly abstract way describes nothing. A snippet of a code example often means more to a Geek than a generic description of how a task could be handled.