Tips for documenting an XML DTD

by William T. Kelly | Feb 19, 2003 8:00:00 AM

Takeaway: Here's what you need to document when developing an XML DTD for a project. Done correctly, this documentation will aid the future maintenance and support of the XML developed for your project.

XML-based development projects often require the development of a Document Type Definition (DTD), which defines the XML code used in an XML document or application.

Even if you are customizing an existing DTD like the DocBook DTD, documenting the DTD is a best practice for a number of reasons, including:

Providing documentation for even more customizations to the DTD, dictating a standard style and approach for any future DTD customizations.
Serving as a QA resource for any issues that may occur with the existing XML DTD versus the issues with the customization added by your development team.

Even if your organization is a bit light in documentation, documenting the XML DTD developed as part of a project can save you from the following ills:

Duplicating XML tags within your DTD
Decreased maintainability and interchangeability of the DTD as the needs and requirements grow for the application

Documenting the DTD you develop is a best practice. Here are tips on documenting a DTD, including preparation and best practices.

Tip 1: Consider the DTD a specifications document
An XML DTD is like a specifications document and should be treated as such for documentation purposes. Your technical writers and analysts should already be familiar with writing functional specs.

Considering a DTD to be a specification for an XML document should fuel what DTD-specific documentation is required by your development organization. The DTD documentation you develop should provide information necessary for your organization’s developers to maintain the XML DTD.

Tip 2: Educate the technical writers and QA staff about XML
To work effectively in an XML-based environment, the technical writers and analysts assigned to document the application are going to have to become fluent in XML.

This tip only applies if your technical writers are actively involved in documentation efforts vs. editing and formatting the work of developers and analysts. It applies to QA staff regardless, because they need the XML knowledge to write accurate test plans.

If this is your first foray into a development project with an XML component, then your developers, quality assurance staff, and technical writers need to mutually decide the level of coverage on what needs to be documented for the DTD so test plans can be written to accurately test the product.

Tip 3: Involve your technical writers in the development of the DTD
Technical writers have the following skills that can transfer over to DTD design and development:

HTML skills, which can translate into a shorter learning curve for XML
Online help and online documentation experience, providing skills in the formatting and presentation of online information

Granted, this tip only applies to writers with a more technical background vs. technical writers that edit and reformat documentation authored by developers. But the involvement of technical writers in the DTD process will give them a leg up on documenting the DTD throughout the development process until the DTD is complete.

Tip 4: Involve business analysts in the development of the DTD
Business analysts have the following skills that can transfer over to DTD design and development:

Analysis
Requirements gathering

If business analysts are your customer interface, they can play an integral role through the documentation of the DTD, as the standard bearer for the customer requirements.

Tip 5: If you don’t have a design document, get one
An XML DTD is an integral design component and should be documented as part of the application’s design in the design document. At the bare minimum, the following should be documented:

DTD files
XML elements comprising the DTD
XML entities

Tip 6: Look at automated tools for documenting an XML DTD
I recommend automating XML DTD documentation tasks to save time. Many of the automated documentation tools produce output compatible with the major print and online documentation tools in use today by technical communicators.

The following tools are useful for documenting an XML DTD:

There are other tools available in the market that perform straightforward, automated XML DTD documentation tasks or are XML development tools that include automated documentation as part of their feature set.

Tip 7: Move beyond developer comments with examples
Documentation can be a subjective term, applying to everything from developer comments about code to substantive online help and print documentation.

The liberal use of examples can help illustrate to readers how the XML elements and entities comprising the XML DTD appear/function within the project.

Documenting an XML DTD
Documenting an XML DTD requires planning, team member involvement, and participation. Skilled technical writers are integral to the documentation of XML DTDs, and their skills are transferable to the development and implementation phases.

1 comment(s)