Technical documentation is a prime beneficiary of XML technology, with standards such as DocBook and DITA. However, while XML revolutionized the way technical documentation is written, it did nothing to help documentation teams improve the collaboration process with the SMEs and other invested parties. In some cases, things got worse, with another layer of complexity added between the documentation team and the documentation stakeholders. Where is the missing link?

By now, you would expect to be able to create documents in XML and share them with other people and collect feedback effortlessly. In theory it works but in practice, few documentation teams reached this point. Here’s a quick test:

• Do you share your XML documents in PDF or another format and loose the XML-awareness in the review process?
• Do you collect feedback through emails or alternative doc formats (PDF, HTML) and have to work it back in to the XML document?
• How/When does your project manager know whether a documentation issue is fixed in the XML source?
• Does he/she maintain an Excel file with dozens of entries and fill up your mailbox?

If you answered no to all those questions, congratulations you fully integrated XML in your process! If not… keep reading!

Nowadays, most software companies use Office applications and Email clients to manage their single-source documentation projects. For instance, they will publish their Docbook files in HTML, send it to reviewers to collect feedback and manage the project tasks through email. Some may use a bug tracking system instead .

Why is it wrong? I see three compelling reasons.

First, the technology should work for you and not the other way around. Spending time publishing XML documents in other formats, or reading through reviewers feedback in a PDF or HTML file, and then integrating it back into your documentation is extra-work that does not create value for your organization.

Second, using multiple formats increases the project inefficiencies and add to the chaos. Some typical pitfalls include:

• Similar feedback multiple times from different reviewers
• Reviewer feedback based on an old version of the documentation
• One person in charge of collecting and merging feedback or begging reviewers to do their job
• One person in charge of tracking documentation corrections

Third, your resources are limited; the time spent with no real value-added could be better invested in new projects or in improving existing ones.

There is obviously a missing link. In essence, this makes sense since XML does not deal with presentation. So when it comes to sharing XML documents in human-friendly formats, one needs a smarter solution. While Office or PDF applications help, they also add another extra-layer of complexity and loose the “XML awareness” of your initial documents.

In the next article I will explain how a solution like LiveTechDocs can help you address these issues efficiently.

I encourage you to post a comment and share your point of view on the “missing link”. I am especially interested to hear more from companies who developed best practices to address this specific issue.

To be continued…

Fabrice Talbot - fabrice.talbot@livetechdocs.com