What is a good rule of thumb to do technical writing that doesn't confuse people

Question

Sometimes I'm such a nerd that not even nerds understand me, or rather, sometimes I cannot put stuff in understandable and simple-enough terms... and sometimes I can but cannot really tell until after.

I like the details on technical stuff, I enjoy writing about them, but sometimes I cannot stop or tell when it is too technical or too abstract to understand. I often end up putting too much detail into stuff thinking that it will help the understanding of some concept, but it sometimes it backfires.

These are all edge cases, I'm not that bad at writing (I hope), but, what would be a good rule of thumb to know when you are probably going to make people dizzy when reading your stuff?, how do you test your analogies?, I'm looking for one or more rules of thumb to know if I'm writing technical explanations right, knowing what to reference and what not, etc.

What is your golden rule for writing about technical stuff to technical people who are not necessarily familiar with what you are writing but are also not noobies in your area?, where is the line?

Answer 1

Assuming your technical writing is for work, you can always ask a colleague to proofread. A lot easier than trying to imagine if you've went overboard or not.

Answer 2

My problem with technical writing was always that I had gathered and learnt far more information producing a project, piece of code, whatever, than was needed for the technical documentation. The rule of thumb that worked for me, was to do a "brain dump" of all the information I had. Then, before anything else (before structuring, grammar, spelling, anything) I would edit the document to remove one-third of the wording without losing any of the sense. (This figure worked for me - YMMV). Then I would start looking at the structure and form of the documentation - introducing if necessary previous examples of structure that were relevant; or standard documents that provided structures useful to what I was trying to achieve.

Once the document had been knocked into a rough first draft by the above process, and by spelling and grammar checks, I would then put the document aside for at least three days. Then I would start the revision process by reading - slowly - what I had already produced.

External editing, review, reading or some mixture of these is an essential. I found with technical writing in particular, I am totally unable to judge whether I have "hit the sweet spot" or not without external input.

Answer 3

There is no silver bullet. This is like asking "How do you know if your software is bug free?". The only answer is: it isn't. Same for technical writing (and all kind of writing): your text will confuse some people. The only way to tell if someone is confused by a document is to make him read.

The important thing is that you should care about how people read and what is their background. A given document should target an audience. And You should try to get all the feedback you can. With experience you should be able to put yourself more easily in someone else's shoes.

In the end writing good technical documents is as wide and complex as writing good code. Remember that the best scientist out there are the one who are able to explain thing in a book or on tv something that took 20 year to discover. So I suggest you follow Yannis suggestion and ask your question on writers because they may help you to ask a more specific question.