Questioning technical publications best practices

Here are the questions I asked of our panelists at our October STC meeting in Austin that further investigated and challenged the best practices listed in the “Tech writers as sales reps?” article on which we focused.

Over the next few weeks, I’m going to group some of the responses into different categories of “best practice” and enter a post for each. I’m just writing what I’ve taken away from the session.

The first has to do with best practices for Document Management Systems based on a question from a reader, which I’ve already posted. The second I’ll title “Best practices for connecting tech pubs to the rest of the business.” The third part will discuss best practices for staffing and suggestions for resourcing, and finally I’ll discuss best practices for structured authoring, a topic on which I think the original article missed the point. There’s a difference between single-sourcing and structured authoring, and the author doesn’t fully realize the missed potential by sticking mostly with single-sourcing.

First, the list of best practices with the questions I posed to our panel.

#2: Understand the value of good documentation.
How do you prove Return On Investment (ROI) for tech pubs at your company? Is the author’s “use customer support to prove ROI” argument a valid one in your experience?

#3: Use documentation to gain an edge.
Does this happen in reality? Do most executives share this view? How have you tried to tell your executives that your documents help you gain an edge?

#4: Have a reasonable ratio of writers to developers.
Do you agree with the author’s 8 developers for each writer approach? How do you estimate your ratios? What’s the right ratio? How have you used this ratio when asking for resources?

#5: Place technical writers somewhere sensible in your org chart.
The author places technical writers in customer support, is that the right placement to you?

#7: Encourage technical writers to meet customers. and #8: Use customer advisory boards to get feedback on documentation.
Customer interaction – discuss constraints on really making this happen. How have you made it happen?

#13: Try out conditional text.
How do you ensure it is used wisely? How do you set up standards? Is this a tool-based decision?

#14: Explore single sourcing.
Do you agree that single-sourcing is the answer? Is he using the old definition of single sourcing, where you don’t really repurpose content? Is the new idea of structured authoring where exploration should occur instead?

#9: Make the right tradeoffs.
How do you ensure that writers focus on content rather than formatting? How can an editing team ensure that the right tradeoffs are chosen? What tradeoffs are there between information quality and quantity?

#10: Pick the right medium for each deliverable. and #11: Provide print for those who need it.
The question is, how can you ignore the costs of 3,000 pages of printed documentation? How much print do each of your departments provide?

Subscribe to the comments for this post

A proliferation of XML languages

From a post to his “ongoing” weblog by Tim Bray:

Here’s a radical idea: don’t even think of making your own language until you’re sure that you can’t do the job using one of the Big Five: XHTML, DocBook, ODF, UBL, and Atom.

With details and scenarios of use for each of the Big Five. Nicely stated, yet I still think there’s room for a Big Six with DITA on that short list. Docbook supporters have discussed similarities here, so you can dig in and make your own decisions.

Thanks for the interesting link, Steve!

Subscribe to the comments for this post