

Technical Writing Tips - thangalin
http://www.rbs0.com/tw.htm

======
dredmorbius
That's not a bad guide, and it touches on a few of my pet peeves (using units,
being precise in quantifications).

It misses the key principles of any documentation, and one that far too many
documentation departments fail utterly on:

1: Grant your marketing department _one_ page for trademarks, and tell them as
politely or otherwise as you care, to fuck off. Your customers/readers in the
midst of trying to solve some problem at 2AM, and/or under the watchful eye of
the CTO/CEO, and/or in a colo's hot or cold aisle with fans blaring and a
melted-down stack, aren't going to tolerate your Yoyodyne Tron-a-matic
Blipvert Flux Capacitor Mark 5-1000[tm] descriptions line after line. It's
"it", "the device", or some other simple pronoun or generic phrase.

2: You're writing to solve a problem, to accomplish a goal. Figure out what
the problem and goal are. If you don't know, get an engineer who designed the
product, or more likely, a solid sales engineer who uses it and encounters
customers who know the ups and downs, to straighten you out. Actually, they're
the ones who're probably best off writing the docs (they probably already
have), and you as a technical writer should squeeze this into your publishing
system and verify correctness of the information.

3: Descriptions of features shouldn't mirror the text or name of a feature,
but _explain their purpose or function_. The quantity of
proprietary/commercial documentation which falls down on this point is
staggering.

4: Document significant product bugs and failings, clearly. This is a
necessary corrolary of the first principle above. The "BUGS" section of UNIX
manpages were (and are) revolutionary.

5: The bulk of the style guidelines in the "Technical Writing Tips" article
referenced are really niggling points of grammar and/or exposition. They're
best left to a last pass through the documentation. Yes, it's helpful when the
piece doesn't read like a 7th-grader better versed in SMS texting wrote it.
But if you're addressing these issues before hitting the four previous points,
you're rearranging the belly button lint on the deck chairs on the Titanic.
It's a complete waste of time to start with, and at least three degrees
removed from the real problem.

------
ikirill
It advises using Strunk and White. I think it would be helpful to point out
that S&W need not be considered all that authoritative:
[http://chronicle.com/article/50-Years-of-Stupid-
Grammar/2549...](http://chronicle.com/article/50-Years-of-Stupid-
Grammar/25497) The people behind Language Log often have something to say
about writing advice.

------
latch
Here's a simple piece of advice I read a while ago and find great:

if it ends with "ly", consider removing it. Or, put differently (teehee), use
adverbs sparingly (teehee).

~~~
baddox
Except, of course, for all the words ending in "ly" that aren't even adverbs.
Ally, fly, costly, supply, bully, replay, folly, family, ugly, elderly, bitly,
etc.

~~~
latch
That's why you have to "consider" it.

------
FreakLegion
A fair amount of this is like _Strunk & White_ in that it's bad advice made to
look good by a disingenuous example. For instance:

 _Avoid using nouns as verbs. [...] avoid saying "He authored ...", instead
say "He wrote ...". avoid using "obsoleted", instead say "made obsolete"._

You won't often see the verb 'to author' in technical writing, but not because
'author' is also a noun. It's simply the case that technical writing aims at
plainness, and 'to author' is a bit hoity-toity. So the example, while
accurate, doesn't illustrate the intended rule.

Anyway, I wish I could say that tips like 'affect vs. effect' are unnecessary
for working writers, but just last week I had to fix several instances of
'insure vs. ensure' in an old document, so. Yeah.

------
asifjamil
Tip number 1: Check for spelling mistakes in your submission before posting to
HN :)

~~~
thangalin
Muphry's Law?

