Tuesday

Develop a Documentation Tool

Today I begin exploring ways of single sourcing the shared measurement fundamentals content. I start by researching other NI-developed solutions. I decide that using XML might work well for this shared text. XML, or Extensible Markup Language, is a custom mark-up language designed to describe data. XML uses tags similar to HTML, the mark-up language commonly used to create Web sites. XML, however, provides additional flexibility. For our purposes, we can use XML for tagging content to share and for tagging content specific to a particular document. I can then create an application that converts the shared XML into formatted versions particular to each help file. All writing and editing would occur in the XML files, our single source.

So, I have identified a few tasks:

• Develop XML tags. For shared text, we'll probably use a tag like this: <shared> </shared>. For text that applies only to my LabVIEW help file, we might use this tag: <labviewonly> </labviewonly>.
• Create a schema, which is a file that defines the structure and the rules for our XML files.
• Create a tool that converts the XML files to formatted versions specific to each help file. I plan on using XSL, essentially a style sheet that handles formatting, to do each conversion. To automate and simplify the conversion process, I'll create an application that allows technical writers to convert their XML with the click of a button.

I like my solution for a few reasons. Because the existing source is already tagged, converting it to XML should be trivial. Another plus is that my solution will work for other groups. If, for instance, other people want to reuse some of this existing measurement fundamentals content, they should be able to do so easily. Finally, because I know several XML experts at NI, I have readily available resources if I run into development problems.

I spend the afternoon mocking up this solution. It looks like it will work, so I decide to draft a proposal that identifies the need for single sourcing and my XML-based solution.