[oXygen XML Editor Blog] - A Short Story of Reuse

A Short Story of Reuse

Posted: 07 Sep 2015 02:38 AM PDT

Give the smartest human in the world a piece of wood and ask him/her to make paper. Give him/her no prior tools and it will take years to come up with a decent process which would result in some brown almost usable thick piece of paper.

This blog post is about reuse, not necessarily reuse of tools and materials, but reuse of knowledge. Humanity has evolved not because each generation is smarter than the last one but because we learned to reuse and pass knowledge to larger and larger audiences and from one generation to another.

Almost all tools that we use today are made up of quite a complex set of components which interact with each other. There is no one person in a car assembly factory who still knows all the pieces and how they come together.

Although using the tool is easier than interacting with all components which make it up, you still need knowledge to operate it and in this day and age having enough people to teach how a certain tool can be used is no longer an option. You need to pass knowledge in other forms, on paper or in some kind of digital form. So I would define technical communication as a means of passing knowledge about using tools to a larger audience.

Reuse in technical communication can be structured on many levels:

  • Reuse written content by publishing it to more than one format (PDF, HTML, EPUB, MS Word).

    It turns out that XML is perfect for publishing content in more than one format. XML is not designed to be consumed directly by end users and its benefit lies directly in this. Your XML content should contain all the data necessary for obtaining all the output formats. So if you are using XML in your technical content, no matter what standard or custom vocabulary, you can safely check the first and most important level of reuse.

  • Create larger publications from existing ones.

    Either using an XML standard like XInclude or using standards with their own diverse and powerful methods of reuse like DITA, or by performing custom techniques you can merge XML content in larger publications.

  • Reuse content written for a certain tool to document the functionality and behavior of a very similar tool.

    In most mature XML standards like DITA and Docbook there is this implemented concept of profiling which allows you to dynamically filter at publishing time content marked with certain attributes from your original XML project. In this way from the same XML content you can publish documentation for multiple similar tools.

  • Reuse smaller pieces of common content in more than one publication.

    Again, using XML standards like XInclude or DITA specific standards like content references you can create and maintain small libraries of reusable XML content, then reuse these components across various publications.

  • Reuse images and other binary resources in multiple publications.

    Because XML content does not embed binary resources, these resources are stored separately and thus they can be reused in multiple places.

So these are what I consider to be the main selling points for using XML in technical documentation. As usual any feedback is welcomed.