Best practices in technical documentation

Version 1
    Share This:

    If you're in Austin, you're welcome  to attend the Society for Technical Communication meeting where I'll be  moderating a discussion about best practices for documentation.


    I'll be moderating a discussion Tuesday night at one of our Society for  Technical Communication chapter meetings. I found this  article, "Tech writers as sales reps? Interface Software's award-winning docs  boost brand, revenues, and customer satisfaction" and thought it has some  great points but I really wanted to get the opinions of others in tech comm to  see how well it holds up in reality. The title sure promises a lot, doesn't it?  It's an excellent read.


    Our meeting announcement made it into the Austin American Statesman  in their "Tech Week" section, so that's exciting. Here's their announcement: The  Society for Technical Communication will host a panel discussion on the practice  of technical communication. Speakers will be Wendy Shepperd, information  development manager at BMC Software Inc.; John Gough, principal technical writer  for Troux Technologies Inc.; Cathy Mallet, information developer at Motive Inc.;  and moderator Anne Gentle, information developer at BMC. 6 to 8 p.m. MCC, 3925  W. Braker Lane. Free.


    If you're local to Austin, come on over and listen in on our discussion. I  don't expect we'll figure it all out in an hour or so, but these articles and  topics sure do get folks like me thinking. Feel free to chime in here on the  blog as well about your opinion on these best practices.


    Summary of best practices

    #1: Create a healthy workplace.

    #2: Understand the value of good documentation.

    #3: Use documentation to gain an edge.

    #4: Have a reasonable ratio of writers to developers.

    #5: Place technical writers somewhere sensible in your org chart.

    #6: Keep technical writers in the loop on development plans.

    #7: Encourage technical writers to meet customers.

    #8: Use customer advisory boards to get feedback on documentation.

    #9: Make the right tradeoffs.

    #10: Pick the right medium for each deliverable.

    #11: Provide print for those who need it.

    #12: Give your writers the right tools for the job.

    #13: Try out conditional text.

    #14: Explore single sourcing.


    Bonus tips

    Bonus tip #1: Hire writers with the right stuff.

    Bonus tip #2: Hire writers who ask smart questions.

    Bonus tip #3: Don't get hung up on tools.

    Bonus tip #4: Provide lots of feedback.

    Bonus tip #5: Insist on timely reviews of drafts.

    Bonus tip #6: Enter publication competitions for feedback.