Technical Writing


I've been having more than my fair share of epiphanies under the shower lately (which surely has something to do with the fact I'm working out a bit and having more showers), and I've started drafting a couple more whitepapers on internal company stuff.

Although I can't discuss the actual contents, the fact that I've felt the need to write them (the "whys and heretofores" of the thing) is of quite some interest.

It all has to do with the traditional lack of social and communication skills on the Engineering side of The Great Corporate Rift between Marketing and Engineering, but with a particularly annoying twist that has been bugging me lately - those strange aloof beings called "architects". Not brick and mortar (or "space and lighting") architects, but systems and network architects.

A systems architect is a strange cubicle-dwelling creature (usually bereft of feathers or any other mating-related adornments) that, unlike your garden-variety engineer, produces copious amounts of paper (or virtual representations thereof), apparently providing conclusive evidence against the theory that engineers can't write properly formatted documents to save their lives.

Those documents are often meticulously laid out, show a liberal tendency in the frequent use of diagrams and tables, contain copious footnotes and annotations, pride themselves in including extensive bibliography and references sections, and, last but not least, have precisely zero spelling and grammar errors.

They are, however, utterly unintelligible to anyone else but another systems architect, and, quite often, are only likely to be fully understood by another systems architect that happens to work in precisely the same field. This is especially the case in telecomms, where any random sentence picked out of a document is likely to include at least two acronyms (a one-to-five ratio between acronyms and "normal" words being quite commonplace).

Which is to say that their effective communication skills, despite their baroque efforts, are pretty close to the average engineers' - but they tend to use ten to twenty times the bandwidth to say the same.

The overall effect of putting a systems architect and a "regular" engineer in front of a non-technical audience is apparently different, but the end results are roughly the same: the systems architect will deliver a PowerPoint presentation, while the other guy will tell a couple of jokes and draw meaningless squiggles on the whiteboard while he explains things, but the audience won't understand what either of them is talking about.

Now, "real" engineers tend to look at systems architects as verborrheic snobs whose ideas "work only on paper", but my point here is a bit different - my take is that while "regular" engineers fail to communicate by sheer lack of skills, systems architects fail to communicate by needlessly complicating things. There seems to be a genuine lack of ability to churn out easy to understand, readable architecture documentation that doesn't border on the arcane.

My guess is that it's due to systems architects having sworn to read (and recite by heart on every third full Moon) all those 3GPP standards (which make IETF and IEEE documents look like comparatively normal English texts). Or to the need to stamp out ambiguity from every single little detail (especially on multinational teams, where English skills vary widely). Or maybe it's just the closest thing to academia in a corporate environment.

Anyway, the reason I'm trying to write a couple of internal whitepapers is to try to discuss, in plain English, a few architectural issues - that, the last time I checked our humungous document repository, spanned at least six different sets of documents authored by moderately obscure sub-groups of a couple of pan-European projects.

Now throw in the cultural rift between the IP world and the GSM world (neither of these groks the other), and you'll get an inkling of that it's like sometimes.

Somehow, a couple of important trees got lost in the forest, and it's about time someone tracked them down again - and left an easy breadcrumb trail for others to follow. And guess what, you won't even need to have an Engineering degree to be able to read my stuff.