Ronny Lam

about://tech

Tips for Engineers Producing Technical Documentation

Although very much M$-Word oriented, this is a very nice list of caveats in technical documentation.

As part of my day job I produce technical documents, proposals and RFP responses for a (mostly) non-technical audience. I read and review even more of the above from sub-contractors, professional services consultants and technical support. I’m as likely to split an infinitive as the next person, but there is stuff I see on a daily basis which drives me crackers. Here are some of the worse crimes against documentation (in my opinion).

But the worst caveat in my opinion is M$-Word. Using plain-text files using Markdown makes documentation much more portable, changeable and searchable.