Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
3  
I'm wondering if this would be best answered at Writers Stack Exchange. Check out their technical writing questions and tell me what you think. –  Yannis Rizos May 11 '12 at 3:51
    
@YannisRizos Well, I'd like answers from programmers though –  dukeofgaming May 11 '12 at 3:54
    
Why are you dismissing Writers without even checking? You don't want answers from programmers, you want the best possible answer you can get. That may come from Programmers, but what's the harm in checking out Writers as well, just in case? –  Yannis Rizos May 11 '12 at 3:58
    
@YannisRizos I'm not dismissing it, I'm already writing a different question related to this (not the same at all). –  dukeofgaming May 11 '12 at 4:00

3 Answers 3

up vote 2 down vote accepted

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.

share|improve this answer

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.

share|improve this answer
    
We both have the same case, but what if that technical writing isn't really for your work? do you have any advice for that? –  KyelJmD May 11 '12 at 3:50
    
@KyelJmD All my technical writing has been for work, so I can't speak from experience. I'd imagine getting someone to proofread your work would as helpful, but it probably wouldn't be as easy to find that someone. –  Yannis Rizos May 11 '12 at 3:54
    
@YannisRizos Proofreading will definitely be the last thing I do... no, really, literally, I'm doing it, but I wouldn't want to annoy my colleague with N revisions. I'd like to get as far as possible without a peer review... and then do it so I don't make the peer in question suffer my ramblings. –  dukeofgaming May 11 '12 at 3:58
    
+1, that answer was the first thing that came into my mind. @dukeofgaming: good writings will often need more than one iteration of writing-proofreading-correcting, I don't think there is a shortcut to this. –  Doc Brown May 11 '12 at 14:16

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.

share|improve this answer

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.