Monday 9 April 2012

DITA without the DTD

A couple of months ago, I led a training course in DITA XML. The first two days were stock slides, concerned with the DTDs, conref and conkeyref mechanism, then, the third day, the one I wrote, was entirely about the DITA philosophy, the semantic nature of the DTDs, progressive disclosure and writing great short descriptions (shortdescs).

Rupert the bear providing progressive disclosure
Rupert the bear providing progressive disclosure

More recently, I've been asked to use Adobe Technical Communications Suite (TCS 3.5) to create content. As for previous assignments, the current documentation is unstructured, does not reuse content, and the help and PDFs are not  single-sourced. That is, the help systems are entirely separate from the PDF and content is copied between the two. I'm assuming this is reasonably common. The team members are all professional writers of a certain quality but, outside of word choice and a few style guide rules, the content varies quite considerably in approach and overall style.

For my part, and probably from my long term exposure to DITA XML, I have adopted many of the writing philosophies that it provides and I work them into my normal output. For instance, progressive disclosure. If I am writing an introduction in a chapter, I don't write, "This chapter tells you about..." and list the subjects, I write a summary that includes high level facts from the subject matter and let the reader make the assumption that this is the subject of the chapter.

Then it hit me, why not formally introduce the writing rules of progressive disclosure and short descriptions into the current writing guide. Why not aim for a DITA-like layout in tasks? Why not, as a team, plan the information set with Task, Concept and Reference topics as if we were using DITA. The double-benefit of this approach is that it results in more consistent documentation, and, should the decision be made in the future to move to DITA XML, we have topics that are ready for the transition.

3 comments:

  1. I try and keep tot his whatever I do. In Author-it I designate topics as you describe although we don't publish to DITA. If you do a task analysis (good practise whatever tool you use) you can designate each topic as well. It's just good practise.

    ReplyDelete
  2. It's really just good practise

    ReplyDelete
  3. There are various online sources to provide you informative details on this topic, but this is one is very helpful.
    TechWhirl

    ReplyDelete