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?
What is a good rule of thumb to do technical writing that doesn't confuse people
writing;technical writing
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.