: Re: Can technical writing suck less I currently have the prospect of writing a considerable amount of technical documentation (describing interactions with an extremely complex online service). I consider

@Phylliss352

Vote Up Vote Down

If you have a background in programming, take a look at Kernighan and Ritchie.

I swear that half of the reason Unix became so popular was the truly amazing quality of that book and a few others like it! I know it definitely inspired me!

At the other extreme, try looking at Unix/Linux man pages, which, while clear, almost never explain anything or even offer usage examples.

Many programmers just don't want to take the time to explain things to lesser beings, or they find it very difficult.

Once you know enough to design and implement something, you know way more than any typical user of it ever will (or would want to!) There are so many facets and underlying background skills needed, that to be competent, many of these have to become second nature, or, to use one of the most pernicious words in the English language, "obvious". When you're close to something like this as a programmer (or to any other intense area of subject expertise), when you simplify it down to what you think are the basics, it may still be incomprehensible or at least confusing to a user.

Also, you probably wouldn't be working on it if you didn't already understand what problems it will solve and why you would want to use it. Things like this are assumed by the programmer before they even start developing and become somewhat unconscious or "obvious".

It can be a major task to discern what most of your audience would be likely to know and understand and then to provide those things which are necessary to bridge the void between them and the technical information you are presenting.

If you present too little, then some readers will be lost or misdirected (see lots of SE questions where people ask about those cute little strings of gibberish which are really fork bombs - some of which have already crashed the OP's computer.)

If you present too much, then people stop reading, feel insulted, get lost in irrelevant details, or mutter things at you about TL;DR !

It is a very special (if usually unsung and under valued) achievement to write something in such a way so that someone who reads it comes away from it saying something like "I didn't know it could do that!", "I can't wait to try it myself!, or "Now, I see!"

You may not have dragons to slay, but if you can make someone feel confident enough to even approach a monster like gimp or inkscape (Those are the sorts of things I usually keep in closets that I'm afraid to open!), then that's a big deal.

There's a huge space for technical writers who can actually explain and teach things - not just document them!

(0)

Login to post a comment!