Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

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

share|improve this question
1  
What corner of tech writing do you have experience with? Software engineering? Aerospace documentation? Biotech? –  Neil Fein May 11 '12 at 4:54
1  
@NeilFein I expanded my post with an edit to address that –  dukeofgaming May 11 '12 at 22:32

3 Answers 3

up vote 6 down vote accepted

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.

share|improve this answer
3  
All writing is hard. Really hard. You don't need to look very far for poor quality fiction either. Poorly written non-fiction? Dime a dozen. But technical writing gets this unfortunate pass at not having to be enjoyable to read because it is utilitarian. It doesn't have to be that way. If people enjoy the text, they will read more closely and remember more. They will care where the Diddle control is. –  Joel Shea May 11 '12 at 14:11
    
One difference is that poor technical writing you sometimes have to read, to do your job. Poor fiction or non-fiction you can just chuck, usually. –  Schroedingers Cat May 11 '12 at 14:36
    
+1 for suggesting "refactoring" of technical documentation. –  Koen Van Damme May 11 '12 at 19:20
    
Along the same lines as refactoring, consider a top down approach. This is most easily done with something that supports hypertext (not hard copy). Tell them precisely the steps/concepts that are needed and provide references to more detail on each step. That way an expert can quickly recall the material and other readers can find the supporting material that explains it - with the added benefit that they can see the overall picture before learning all the details. This may even have the side benefit of making updates easier when the details change, but the overall process does not. –  Joe May 18 '12 at 20:49

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.

share|improve this answer
    
I don't agree, because for technical writing, the approach of the reader is often different to the normal reader. Most of the time, technical documentation is consulted, not read. While some of what you say is right, you need to try it on someone in the target readership, and see if they use it as a resource. It is more helpful, IMO, to see technical documentation as a tool, so the questions regarding structure are "does this tool help me do my job", not "can a numpty read it". –  Schroedingers Cat May 11 '12 at 12:02
    
As I read it, the question is about clarity and that goes well beyond structure. We don't really know what type of document was really being asked about; I took it to be a technical book, but whether it is a book or a help file or a blog post, ultimately you want to to engage your readership. As a author, you goal is to make them NOT want to just skip down to the charts and/or code. Of course you should give your writing to someone familiar with the subject. My point is that if you have made it clear enough for a layman to not hate, then you're on the right path (this does not mean to "done"). –  Joel Shea May 11 '12 at 13:52
1  
Yes it goes beyond structure, which is where I agree with you. But for a technical document - IME at least - I want to find the section that says "How to Diddly your Squat", which I then want to be able to read at my level, and know how to Diddly my Squat. If it is too detailed, then I am less likely to read it. –  Schroedingers Cat May 11 '12 at 14:33

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.

share|improve this answer
1  
+1 for focusing on getting the content right first, not the wording or organization. SMEs are most valuable for helping you find the message: what it is that you need to tell users (not how). Their special expertise helps with content correctness and completeness (relative to the scope of the message). Help them by letting them know that that is what you're looking for from them, first and foremost. –  Drew Jun 26 at 6:01

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.