chuck.goolsbee.org  goolsbee.org, serving useless content from an undisclosed location since 1997

February 21, 2010

The 7 Rules for Writing World Class Technical Documentation | SCALE 8x – 2010 Southern California Linux Expo

Filed under: Technology,Writing — chuck goolsbee @ 9:47 am

The 7 Rules for Writing World Class Technical Documentation | SCALE 8x – 2010 Southern California Linux Expo.

Saw these seven nuggets of wisdom from Bob Reselman via Twitter and my friend (and fellow speaker @ Macworld Expo) Dan O’Donnell.

Writing a technical document is hard. Reading a poorly written technical document is harder, and probably more painful than writing one. It takes a lot of work to create a clear, accurate, engaging piece of technical writing. Thus, in order to make life a little easier for all parties involved, I am going to share with you the 7 Rules that I follow when creating a piece of technical documentation.

The 7 Rules are:

1. Dry sucks
2. Before you start, be clear about what you want your reader to do after you end
3. Write to a well formed outline, always
4. Avoid ambiguous pronouns
5. clarity = illustrations + words
6. When dealing with concepts… logical illustration and example
7. Embrace revision

Wish I could attend the session in question.

No Comments

No comments yet.

RSS feed for comments on this post.

Sorry, the comment form is closed at this time.

Powered by WordPress