Summary: Standards for Documenting XML?

[Sheldon Kohn <Sheldon -dot- Kohn -at- onlineinsight -dot- com>]

Hello All,

Please forgive my delay in posting this summary, but we have been busy. In
case you have forgotten, I posted a request asking for people to share
standards for documenting XML. All but one response I received were requests
for a summary of the responses. It seems that this is a new area and that
people are interested.

I also received the following response, which I include in its entirety:

What has worked for us in the past, with both XML and HTML, is to create
self-documenting documents out of the templates.  

For example:

<topic>
	<intro>Provide a brief introduction to what is being discussed in
the topic, as well as any prerequisite and related information</intro>

<procedure>
All procedures must be contained within procedure tags.
	<step>Each step must be enclosed in the step tags. The steps should
be formatted ...</step>
</procedure>
</topic>

Here's what I did for our manual:

In the first part of the discussion, the description included attributes and
levels for a product. First, I explained what an attribute is and a what a
level is. Then, I included sample code and discussed each sample. I was not
completely happy with the results, but I think that some formatting
(call-outs and sidebars) will help this section. 

In the second part of the discussion, I documented XML commands. Basically,
I inserted sample code and followed this with a discussion of each tag. This
section seems to me unsatisfactory, and discussion of the "right" approach
took a lot of time in our planning and review sessions. I felt that the
Development Team was side-tracked by this discussion, so I was hoping that
other whirlers could share their standards.

I remain interested in exploring this topic further. If anyone has more
information, please feel free to contact me directly.

Regards,

Sheldon Kohn

"Car Dieu le Roy du ciel le veult, et cela est revele per la Pucelle."