2009-06-09

A couple things you should never do in technical writing

  1. Be condescending.
  2. Be self-congratulatory.

Condescension

A typical software example is “The System can frobnicate, twiddle, and twirl, but don’t worry, you can do it all very easily with the new System Icons!” When you say “we made it easy” what you really mean is “We think you users are stupid, so in Our infinite wisdom we graced thee with operations so simple even a caveman would understand”. Another example of condescension are most uses of the words “trivial”, “obvious” and “clearly” in math texts.

There is such a thing as natural complexity, but bad writing and bad design are much more common. Don’t blame the readers for your bad writing, and don’t blame the users for your bad design. If you can afford, hire a real editor and a real UI designer to fix them. If you can’t, well, then don’t blame your clients!

Self-congratulation

“The System was brought to you by the Department of Systemic Systematization, under the kind patronage of the University of Systems Research. It is provided free of charge to the public in the USR’s mission to help education as part of our social responsibility program that” etc. etc. etc. Self-congratulation is not offensive like condescension, but it’s still annoying and useless. It violates the first commandment of technical writing: Thou Shall Not Waste Words. The reader opened your manual to learn how to use the system, not to learn how amazing you are.

Often self-congratulatory sections are written against the will of the author, due to some kind of political pressure. If you’re a writer in this situation, see if you can tuck it politely out of the way, in the last section or as small print.

— leoboiko, 13:42:49

|comments| = 3

3 comments

  1. Agreed 100% (I’m a technical writer).

    In general, it is always better to limit the usage of certain parts of speech like adverbs or adjectives unless they are really necessary and stick to JUST the facts without any form of personal judgement.

    Comment by Fabio Cevasco — 2009-06-10 08:34:47

  2. That’s true of any kind of writing. BTW, are you a (LISP programmer?)

    Comment by Ferruccio — 2009-06-10 09:14:47

  3. @Ferrucio: Yeah, well, perhaps someone want to write an avant‐garde novel where they offend the readers and praise themselves all the time, and I have no business criticizing it. But to do that in technical writing, of all things, is IMO inexcusable.

    And yes, the CSS theme is (lispnik style).

    Comment by leoboiko — 2009-06-10 10:42:29

Leave a comment