This guide provides a set of best practices that will help you with the task of
documenting an XML schema defined by an XML DTD. These best practices were
established by the developers at Quarksoft, LLC who have
extensive experience in technical documentation, XML data modeling and development.
Start With a Good XML Data Model
A good XML data model can make documenting your DTD 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:
- Naming conventions - The lack of naming conventions can result in very inconsistent
and cryptic names for the elements, attributes and types defined by 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.
Embed Comments inside Your DTD
Comments can be added to DTDs using the following comment syntax
<!-- comment text -->
Using this syntax, you can embed your comments by placing them above the definitions
for the elements and types you wish to describe, making them easy to maintain as
the DTD changes over time.
For more information on embedding comments inside a DTD visit
Documenting XML DTDs.
By embedding comments inside your DTD, you create a "self-documenting" data model
that will be easier for XML data modelers and XML programmers to understand.
Comment What You Can and Annotate Everything Else
To document your DTD, you should describe the following XML schema 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. Your data model may also include elements, sometimes referred to as "association
elements", that are used to create many-to-many relationships between objects.
For these types of elements, your comment should describe the purpose of the relationship.
- 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.
- Types - Most types are used to create specific elements or attributes. In
these cases the types should be commented the same way as elements and attributes.
- Enumerations - For elements, attributes and types that have a list of enumerated
values defined, you should comment each of these values.
The descriptions that you add to these XML schema 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.
Embedding comments in your DTD does have some limitations. These include:
- There is no way to comment attributes.
- You may not want to include comments in the DTD itself to keep the file size to
a minimum.
To get around these limitations, you can use a tool like
TechWriter to annotate the DTD with external comments that can be merged
together with the embedded comments to produce the complete documentation.
Use a Documentation Generator
Having a self-documented DTD is helpful for data model design and maintenance, but
there are many instances where you are going to need actual data model documentation.
Here are a few examples:
- Data Model Documentation - If you are creating an DTD for a client, data
model documentation is typically a required deliverable.
- End-User Documentation - While your XML data modeler may have the DTD expertise
needed to read and understand the data model, many users of the XML may not.
These users may be consumers or producers of the XML data that is defined by the
DTD. You will need to provide them with some form of documentation that will help
them understand the data model.
- Data Model Reviews - Not all participants in a data model review are going
to have the same level of XML schema knowledge and expertise. Your subject
matter experts may not be technical at all. To facilitate such a data model
review, you will need to provide documentation that anybody can read and understand.
Fortunately there are tools like
TechWriter that can be used to generate the XML schema documentation automatically,
leveraging the DTD and the comments you've embedded inside it.
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 DTD 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 DTD is constantly changing.
For more information please visit:
