Sunday 20 September 2015

Author-it and metadata

Metadata is data about data, or in a technical writing sense, data about information. Author-it has some mechanisms for working with metadata, primarily variables, but how do those transition to the published output?

Author-it is a Component Content Management System based around Microsoft technology that allows teams of authors to collaborate and recombine information to various outputs including help systems, Word documents (and from them PDF) and web knowledge bases. The main window looks like this,



A bit of research this morning and a light-bulb moment allowed me to transfer my variables into both the HTML outputs (easy!) and Microsoft Word (less obvious).

To give a concrete example of what a variable is and how it helps, say for instance I set the Product variable on each of a pair of books containing the same topic to be "banana" and "pear" they can share the same "What is fruit?" topic that mention the product variable,



But sometimes we want to transfer over metadata about the information that doesn't form part of the narrative. How do we get this across to the published output?

Well, in the case of your HTML it's simple and fully documented in the Author-it Knowledge Base, simply edit the HTML template that you are using and add the Author-it namespace and variable name in the template file for instance in the metadata,

<meta name="object_rev" content="<authorit:SYS_OBJECT_REVISION>"/>

Which inserts the object revision into the metadata of each HTML topic.

And in the case of Microsoft Word, after my light-bulb moment, I created a new hidden style called metadata in Microsoft Word and Author-it and included the variables in a new topic called metadata with the Print heading empty which I tagged on the end of my book.



That way, the variables turn up in the Microsoft Word document hidden and ready for post-processing if, for instance, you want to use a macro to move them into the document properties.

If you know a better way of transferring variables into Microsoft Word and PDF output then let me know in the comments. Thanks