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 very typical (at least for me), one can tend to over-explain and get the adverse effects out of fear of under-explaining and making people feel dumb.
What is a good rule to take something you've written down and make it shorter and sweeter without stripping technicality?. What criteria can one follow to condense/compress information and make it clearer at the same time?
Edit: I'm currently writing a whitepaper, which mixes formal research with software engineering topics
This post was sourced from https://writers.stackexchange.com/q/5641. It is licensed under CC BY-SA 3.0.
3 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
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.
This post was sourced from https://writers.stackexchange.com/a/5644. It is licensed under CC BY-SA 3.0.
0 comment threads
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 comment threads
The key question to ask in deciding if something is in or out in technical communication is this: What would the user do differently if they knew this?
If the answer it that they would not do anything different, then leave it out.
Once you have determined if the user would do something different if they knew this, ask, what would they need to know to do this with confidence? Focus on the completion of the action. That which supports the completion of the action is in; that which does not is out.
But remember that confidence is key to action. The reader needs to feel that they understand the consequences of an action before they perform it. They need to know what good it will do, and they need to know it will not cause harm. If it helps the user understand the consequences of the action, it's in. Otherwise it's out.
0 comment threads
0 comment threads