LiveTechDocs BETA

Managing Writers Cover

Richard L. Hamilton is the author of the excellent, recently published book Managing Writers: A Real World Guide to Managing Technical Documentation. After  managing technical documentation for more than 10 years, Richard gives us in this book a goldmine of useful and practical advice for managing documentation. When we heard about the book (thanks Scott Abel!) we read a copy right away and liked it so much that we came back for more and asked Richard for an interview focused on managing documentation review and XML schemas myths and realities.

Enjoy!

In Managing Writers, you offer very useful methodologies for Documentation Managers to improve project management by developing healthy, productive relationships with the Writers. Documentation review can become a project bottleneck, independently of the Writers, as it requires the involvement of many Reviewers who are only partly dedicated to the Documentation.  What can Managers do to make sure that the documentation review is as efficient and enjoyable as possible for everyone?

This can be tough. In Agile environments, for example SCRUM, reviews are built into the sprints and a sprint cannot be called done until all of the reviews are done. In more traditional environments, you may need to work harder to get reviews into the schedule. However, I think getting reviews into the development schedule is important.  The other thing that helps is for managers to build relationships with those who manage the engineers their team supports. Finally, include reviews in your schedule and review your schedule in project status meetings. Since reviews often occur in the busiest part of a project it can be hard, but persistence and visibility help. You also, of course, need to make the review process as painless as possible for all involved.

What methods or tools can help Reviewers provide accurate feedback and Writers manage it all?

The key is to keep the whole process simple and easy for reviewers. Reviewers should not have to exert any effort beyond reviewing and writing comments. This means making content available in an easy to read form (online is great, but other formats, even print, may be necessary at times) and making it simple for reviewers to write comments.

Second, pick the right people to do the review and target reviews to as few people as required to get what you need. Few things bug
reviewers more than having to review something outside of their area of responsibility or expertise.

Third, writers need to work with reviewers ahead of time to schedule review time and make sure the reviewer is committed and has adequate time. Writers should treat reviewers time as sacred and make sure they don’t waste their time with unnecessary reviews of material that is either not ready or already reviewed.

Finally, follow-up. Writers should not be shy about following up to be sure reviews are happening, to query reviewers about their comments when they aren’t clear, and to thank their reviewers when they’re done.

As a Documentation Manager, what metrics could be used to measure the performance of the reviewing process?

I tend to be cautious around metrics. That said, I think it makes sense to keep track of how well reviewers and writers meet their milestones. It’s also good to talk with reviewers periodically to see if they are satisfied with the process.

I do not like to track metrics like the number of comments as a quality measure. Anything you track is likely to cause some change in behavior. If you consider fewer comments to be “better,” you can bet you will get fewer comments, possibly losing important information. If you consider more comments to be “better,” you can bet you will get more comments. In neither case are you likely to get higher quality comments.

In the section of Managing Writers dedicated to XML schema choice, you advise Managers to thoughtfully weigh in their options in deciding whether to implement DocBook or DITA XML schema. When walking documentation conferences or looking at documentation billboards, all one can see is DITA. Why is that? What should Managers make of this?

Sometimes a technology gets hot, and DITA is certainly hot. Since conference managers and program committees want to attract lots of people to their conferences, they will favor hot topics. I do think that popularity is a factor to consider in selecting a schema, but it should not be at the top of your list. Unless a particular technology does what you need it to do, it doesn’t matter how popular it is.

The question for managers is whether the technology is evolving, whether they can get the technical assistance they need, and most important whether the technology will help them achieve their business goals. I think you can say yes for the first two for DocBook and DITA, and of course, the answer for the third question depends on your business goals.

You mentioned in Managing Writers that more people use DocBook than DITA. Is it possible to estimate how many people or projects use DocBook and how many use DITA?

While DITA is gaining users quickly, there is a lot of existing content in DocBook. DocBook has been around for nearly 20 years, and has been used by many companies and open source projects.  You can see a partial list of DocBook users at http://wiki.docbook.org.

Also, while this is far from a scientific survey, I did a quick search for “-//OASIS//DTD DITA” (the DITA DOCTYPE) on Google and got about 300 hits. A search for “-//OASIS//DTD DocBook” yields over 7,000 hits.  While un-scientific, I think it shows a large body of DocBook content that flies below the radar.

Managing Writers depicts the DocBook community as vibrant, active and supportive. As a Manager who has just chosen to go with DocBook, where do I find the community, and what support can I expect from it?

I’d start with the DocBook mailing lists on OASIS. You can find them at: http://docbook.org/help. This page also has references to other resources. The mailing lists, esp. docbooks-apps, are great for technical and non-technical queries, including detailed questions. The list is active and lively. Queries there will get a quick response, often from members of the DocBook Technical Committee, which manages the standard, and other experts.

Right now, the main printed reference, DocBook: The Definitive Guide, is being revised for the latest version, DocBook 5.0, and the current printed edition is out of date.  You can get to the latest version online at http://docbook.org, and a new edition of the printed book should be out later this year. The other essential resource for power users is Bob Stayton’s DocBook XSL: The Complete Guide, which has everything you need to know about the DocBook stylesheets.

To be clear, while I am a long time user of DocBook (my book was authored in DocBook 5.0, and I used the DocBook stylesheets to generate all aspects of the book except the cover art and two SVG figures), I am not religious about DocBook. There are clearly situations where I would recommend DITA without reservation.

Lastly, as a Documentation Manager, what features would you like to see on LiveTechDocs to better manage documentation review?

I spent some time on the site over the last few days and it looks like you have some good capabilities there. I think a few things would make it even easier to use:

1. make it easy for a writer to generate a URL that will take a reviewer directly to the document being reviewed.
2. integrate with CMS/versioning so that an author can easily update the version being reviewed.
3. make signing up reviewers as easy as possible. Ideally, they could be signed up by authors so that even the first time in, all they’d need to do is follow a link to the document and go.
4. Another thought is that it might be good to include information on the review pages that would help the reviewer. For example, you might let writers include the schedule, contact information, and anything else that would make life easier for reviewers.

Overall, I think you have a good capability that should make it easier for reviewers, writers, and managers to do their work.

Thank you very much Richard!

You can learn more about the Managing Writers at XML Press book and purchase it on Amazon.