: How can you write less to say more? Sometimes you can write a lot without saying anything, sometimes you can say a lot but get little through the reader. In technical writing the later is

Vote Up Vote Down

My experience is in software documentation (particularly programming interfaces), so I'll answer from that perspective. I think these principles are pretty general, but I've never written manuals for, say, airplane repair.

Generally, you want your documentation to say all and only what is needed for the reader in his current context. For example, if you're documenting a programming interface and the signature of the call already contains a return value, typed arguments, and exceptions thrown, don't repeat that -- it's already in front of the reader. Do, however, explain any of those that need clarification. What does it mean if it returns null? Are there semantic limitations on the parameters that aren't encoded in the type system (e.g. that integer must be positive)? Are there preconditions (this call is only valid if such-and-such state exists)? These are all cases where you will need to say more, not less, but the point is to not say the stuff that's unnecessary.

This doesn't mean you'll never repeat information. If there are three different contexts in which such-and-such piece of information about your system is important, you need to say it in all three. Whether you do this with duplicate text or via links/see-alsos depends on the specifics of your situation.

Some people approach the problem of concise writing by writing everything down first and then pruning. I prefer to work up from the bare bones. I start with (say) the signature of the call, then ask myself what else the reader needs to know in order to use it, and I write that. (Ideally I will use it rather than just speculating.) The first round of review by the SMEs (subject-matter experts) is focused on whether I left anything out or have any errors; reviewing for the text itself comes later. I've found, by the way, that SMEs are more responsive when I don't drop large rambling tomes on them. :-)

My answer boils down to "don't get verbose in the first place", but what you asked was how to trim down an already-written piece. For that, I go in decreasing chunk sizes (section, paragraph, sentence, word), asking "is this X really necessary?". If not, mark. I do this on paper, not in a text editor, so I can complete the entire review pass before changing anything. I do it in this order because there's no point in tuning a sentence if its entire paragraph or section is going to go away. Do the biggest parts first and then narrow your focus.

I've been talking so far about reference documentation. Other types of documentation, such as tutorials, call for a more verbose style that reinforces previously-taught information. Don't generalize my advice about concise writing to situations where this is not the goal.

(0)

Vote Up Vote Down

The techniques are no different than for any type of writing, really. You write everything there is to know about the topic down in the first draft, then you go back and cut out what isn't needed. Once you have everything in front of you, it will be much easier to see what should be there and what shouldn't. Do they really need to know that there are twelve different kinds of widgets? That each has a different process for manufacturing? Do they need to know that here? Cut about half the words on the page (and I'm not kidding, 50% the words in your first draft are probably not carrying their own weight) and rearrange your text around so that the most urgent, important stuff is in the front and the nice-to-knows are closer to the back.

Now give it to someone who knows nothing about widgets and see if by the end they know something. While someone with no prior knowledge may not know how to build a widget by the end, if they understand what it is and that there are a dozen different kinds and that a sand widget is the most interesting of the bunch, you are on the right path.

One of the things to keep in mind is that your reader is probably pretty smart, maybe even smarter than you, just less knowledgeable about this subject. Don't worry about those that aren't. You are more likely to alienate both readers if you try to over-explain things to them. Readers don't want to be coddled, they want to be shown.

(0)

Vote Up Vote Down

Most of the time, the answer to this is structuring of the writing. I work in Software development, and you are right that a lot of technical documentation is appallingly overdone.

The straightforward answer is to take stuff that is written more than once, and write it once in a definitions or explanations section. It is rather like refactoring code - take the verbosity out and put it centrally, so that you can see the flow of the code, and only refer to the details at the points you need to.

Ideally, someone who knows the system fairly well, should be able to look at a short page of technical instructions to find out how to do something they have not done before. At the same time, a new user should be able to achieve the same thing, but probably looking up a lot more of the details (What is a Doodlesquat? Where is the Diddle control? How do you Activate The Centuran Protocol?)

Writing good and clear technical documentation is a really difficult thing to do, as demonstrated by the general quality around.

(0)