Tips for writing documentation

ROSE Blog: Rikki's Open Source Exchange

Yesterday I received a phone call from a grad school buddy who is now writing press releases and marketing for a technology company. I told my friend that her press releases were probably much better quality than the ones she received as an editor for a regional newspaper. She replied, "They're great until the engineers review them and change everything back into engineer-speak."

It's timely that this morning I ran across Carla Schroder's recent documentation blog posts: Tips for Documentation Writers (This Means You Too, Ace Coders) and More Tips for Documentation Writers (You Too, Ace Coders).

Of course, if you were in Janice Gelb's LISA presentation, "WTFM: Documentation and the System Administrator," your documentation has probably improved by leaps and bounds in the past few weeks. Janice's presentation slides and additional materials are still available online, too: http://www.usenix.org/events/lisa08/tech/tech.html#gelb

I'm also reminded of something an attendee said at Janice's session. He recommended that everyone read The Elements of Style . If you haven't read it in a while, it's not too late to add it to your Christmas wish list.