still talking to myself about technical writing

Another Pre-amble

Referring, once again, to my article on documentation for Red Hat Magazine entitled ‘Four rules and an axiom’

I’ve posted a further comment in reference to thoughts posted by two readers.

And, like my first, self-generated comment, I had links in the comment.

<tone mode=”wearied & pissed off”>

/* It’s hypertext for pity’s sake. In-line links to other material are the entire point of this environment’s existence. If we can’t in-line link, we may as well start using Gopher again. */

/* I hasten to add: this rant isn’t aimed at the folks running Red Hat Magazine. They’ve clearly got both a ‘lots of links probably means comment spam‘ policy and a ‘strip links out of posts we let through just in case’ policy. */

/* Given the bane and blight that is comment spam, neither policy is entirely surprising. It’s still annoying enough that I’ve been moved to this little rant against the whole mess. */

</tone>

As you might infer from the above, the comment has appeared sans links. So I’m re-posting the copy below, complete with anchor tags and title attributes.

Comment as Originally Written

Don in Brooklyn wrote:

Speaking of jargon – numbering your five rules 0)-4) is a problem! Especially when it is followed by reference to the “five rules” when you have just finished with Rule 4.

and Tigger23505 wrote:

having a rule 0 smacks of jargonism. What do you do when you have a rule that absolutely must head the list. The common solution is to call it rule 0. The other thing to keep in mind particularly in technical writing, is that many in the target audience are used to things like numbering the bits in a 32 bit word 0-31.

FWIW, although I’m aware of the programmer’s habit of ordering from 0 rather than 1, I wasn’t primarily thinking of that when I decided to call my axiom ‘rule zero’.

I was mostly thinking of the Zeroth law of thermodynamics and, to a lesser extent, Isaac Asimov’s Zeroth law of Robotics.

In both cases, the zeroth law serves as a foundation stone or fundamental beginning point from which further laws can be derived (in the case of thermodynamics) or newly understood (in the case of Asimov’s Robotics Laws).

High falutin’ company I’m aiming to put my laws in, I’ll admit. Never let it be said I lacked ambition, however. Capability? Well that’s a whole ’nother question.

1 Comment »

  1. edu said,

    July 21, 2016 at 11:30

    edu

    non-standard deviation » still talking to myself about technical writing

RSS feed for comments on this post · TrackBack URL

Leave a Comment