ROSE Blog: Rikki's Open Source Exchange
ROSE Blog: Rikki's Open Source Exchange

Tips for writing documentation

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.

Comments


Print this page. Recommend
Slashdot it! Delicious Share on Facebook Tweet! Digg

 

In the US and Canada, Linux Magazine is known as Linux Pro Magazine.
Entire contents © 2009 [Linux New Media USA, LLC]
Linux New Media web sites:
North America: [Linux Pro Magazine]
UK/Worldwide: [Linux Magazine]
Germany: [Linux-Magazin] [LinuxUser] [EasyLinux] [Linux-Community] [Linux Technical Review]
Eastern Europe: [Linux Magazine Poland] [Linux Community Poland] [Open Source DVD Poland]
International: [Linux Magazine Brazil] [EasyLinux Brazil] [Linux Magazine Spanish]
Corporate: [Linux New Media AG]