Technical Writing Tips

http://www.rbs0.com/tw.htm

by thangalin • 15 years ago

44 8 15 years ago

rbs0.com

asifjamil• 15 years ago

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

thangalin• 15 years ago

Muphry's Law?

ikirill• 15 years ago

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... The people behind Language Log often have something to say about writing advice.

latch2• 15 years ago

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• 15 years ago

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.

latch2• 15 years ago

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

FreakLegion• 15 years ago

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.

dredmorbius• 15 years ago

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.

Technical Writing Tips

Related Stories