Designing to Write

Up until I was about 24 or so, I used to think that my left-brain orientation would prohibit me from ever being a passable writer. Writing and composition were more art in my mind than anything else - those artsy Liberal Arts majors could have it and I didn't need it.  My thinking was such that at Pitt, I took "Calc 4 - Differential Equations" for kicks my senior year even though neither my Major (Computer Science) or Minor (Mathematics) required it. This was the safe choice for me - it was an easy 4 credits and I didn't have to sweat out some course with major writing requirements in it.

That thinking totally changed once I joined industry. It turns out that I learned quickly that writing is an important part of the professional engineer's job as all sorts of software development phases require the ability to communicate clearly with the written word. We develop all sorts of documents such as Requirements Specifications, Software Architecture Definitions, High and Low-Level Software Design Documents, and contribute to user manuals and guides.

The epiphany for me was when I was working at the Rockville, MD site in 1986 and took a one day course entitled something like Designing to Write. The course was for software engineers and the basic premise behind the course was that:

• Technical writing is more craft than art.
• Any competent engineer is able to be a competent technical writer if they learn a small number of simple techniques and if they are willing to apply those techniques to their writing.
• There are many parallels between the craft of technical writing and the software design and development process.

The last bullet really resonated with me. I have always been a "code falls out" type of engineer. By this I mean, that if I spend the time up-front in defining a coherent architecture and low-level design, the implementation of the code just sort of falls out. This is a much more pleasing way to develop software than to try to close on architecture and design issues while coding.

The techniques and craft portion of the class focused on stuff that I had learned in High School but the refresher was useful. Items like:

• Paragraphs have a major theme.
• First sentence of the paragraph summarize the theme - subsequent sentences flush it out.
• Use of lists and when to use ordering.
• And so on.

For technical writing, I find that if I simply take the time to flush out a good, detailed outline of my document up front, that the actual development of the document goes so much smoother. The outline should be sufficiently detailed that each section heading can be developed in 2 or 3 paragraphs. If I do that and then just take care of the craft aspects (the blocking and tackling), then I find that I can crank out decent amount of design documentation in a fairly short period of time.

This may seem bloody obvious, but you would be surprised at how often professional engineers don't do this. They just start filling in a document template on the fly or they just start writing code before designing.

I learned this lesson the hard way recently. A colleague asked if I would write a Letter of Reccomendation for her application to Graduate School. That was in early October with a deadline of the end of the year. I was flattered that she thought highly enough about me to ask and was glad to agree to her request.

As an aside, after accepting the request, I did experience some discomfort when I read that among the attributes of a "Good Person to Ask to Write a Letter of Reccommendation" were that they:

• Be well known
• Be able to write a good letter

Yikes. So I went back to my colleague and told her that I would be willing to give it the old college try on the letter part, but I couldn't do much about that first qualification. (Who in the hell is Joe Nedimyer?)

Well, my bad habit of procrastinating kicked in and I found myself in the middle of November with still no letter developed. So I blocked off some time on the Friday before Thanksgiving (my first day off for the holiday).


My goals for this letter were:

1. Relate my experiences with the candidate highlighting positive attributes.
2. Where possible, highlight attributes that are applicable to the field of chosen study the candidate would be pursuing (that is draw linkages).
3. Don't make the candidate or (most importantly) myself look like a douchebag. (That last part is sometimes hard to avoid).

So do I practice what I preach? Nahhh. I just fired up Word and started core dumping and refactoring paragraphs and generally just winging it. After about an hour of this, I took a look and proofed the first draft and it was horrible.

So, at that point, I reset everything and tossed it out. Went to grab a favorite Adult Beverage. Sketched out an outline in about 15 minutes and 20 minutes after that, I was looking at a draft that (at least) I really liked. I hope my colleague liked it as well.

Now before some anal-retentive blog reviewer pours through this site and finds some dangling participle or horrible use of tense in this blog, please understand that I am not implying that I write well - but for an engineer, I don't do too badly.

Also, the editing software for this blog has recently been updated. For the life of me, I cannot find the spellchecker functionality. So please forgive the spelling.