Best Practices Guide for Documenting XML Instances

This guide provides a set of best practices that will help you with the task of documenting XML instances.  These best practices were established by the developers at Adivo who have extensive experience in technical documentation, data modeling and development.

Start With a Good Data Model

A good data model can make documenting your XML instances a much easier task.   Although it might not always be an option, if you have any influence over the data model, here are some key areas that you should look out for:

  • Schema definition - Documenting an XML data model is easier if an XML Schema has been defined for the XML instance.  Before attempting to document the XML instance, find out if an XML Schema Definition (XSD) or XML DTD exists for the given XML.
  • Naming conventions - The lack of naming conventions can result in very inconsistent and cryptic names for the elements and attributes that appear in your data model making it more difficult to document them properly.  Applying good naming conventions to the data model will promote better readability of the documentation.

And even if you do not have any control over the data model, a quick review will help you better estimate how much time it will take and set expectations for the completion of the documentation.

Describe Your Data Model

To document your XML instance, you should describe the following data model components:

  • Elements - Elements are typically used to model real world objects.  The comments for these types of elements should describe what that real world object is.
  • Attributes - As elements typically represent real world objects, attributes are typically used to represent properties of those objects.  Attribute comments should describe what those properties are and how they are represented.

The descriptions for these data model components should be concise and consist of one or two sentences.  If there is additional information that is important to document, you should consider structuring your comments into two parts: a summary description followed by a remarks section.  The remarks section can be used to include the additional information.

Because there is no formal way of adding comments to an XML instance, you will need to use a tool like TechWriter to annotate the XML instance with external comments that can be used to produce the complete documentation.

Use a Documentation Generator

Creating documentation for an XML instance can be difficult because the data model is not explicitly defined. Fortunately there are tools like TechWriter that can be used to generate the data model documentation automatically, deriving the data model from the XML instance and applying the external comments that you created.

Make Documentation Part of Your Development Process

If your project is using automated build tools like Ant, NAnt and MSBuild, you can make generating the documentation part of the automated build process for the system.   By having the documentation as up-to-date as the system itself, your project will benefit in the following areas:

  • Knowledge Capture - While some development methodologies such as Agile ascribe to a "document late" philosophy, projects can suffer greatly when they lose a team member.  The knowledge of a system literally walks out the door.  Documenting as you go minimizes the impact of losing a team member and makes it easier for new team members to ramp up.
  • Communication - Documentation can help communication among project team members.  The project manager can better assess the status of the project.  Subject matter experts can verify that developers are on the right track.  And mistakes can be identified earlier in the project life-cycle.
  • Documentation Quality - Scrambling at the end of the project to throw the documentation together for the final deliverable can result in the data model not being documented properly, if documented at all. 

By making documentation part of your development process you will ensure that the documentation is always in sync with the data model, even in extreme programming environments where the data model is constantly changing. 

For more information please visit: