This guide provides a set of best practices that will help you with the task of
documenting an XML schema defined by an XSD. 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 XSD 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.
- Global components - XSDs allow schema components to be defined either
locally within the parent component or globally so that the component can be reused. By
using global components in your data model, you will maximize reuse and reduce the
number of components that you need to document.
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 XSD
XSDs provide a mechanism for adding comments to elements,
types and other schema components. These comments are included as part of the definition
of the schema component using the annotation tag, making them easy to maintain as the XML schema
changes over time.
For more information on embedding comments using the annotation tag visit
Documenting XML Schema Definitions.
By embedding comments inside your XSD, 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 XSD, you should add
comments to 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.
Not all of the information you want to include in the documentation may be
appropriate to embed in the XSD itself. And you may want to keep the size of the
XSD to a minimum. For this type of information
you can use a tool like TechWriter
to annotate the XSD 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 XSD 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 XSD for a client,
data model documentation is typically a required deliverable.
- End-User Documentation - While your XML data modeler may have
the XSD 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 XSD. 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 XSD
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 XSD 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 XSD is constantly changing.
For more information please visit:
