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?