[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: Documenting DTD's
- From: "Bullard, Claude L (Len)" <firstname.lastname@example.org>
- To: XML Everywhere <email@example.com>, Bob Wait <BWait@ariba.com>,firstname.lastname@example.org
- Date: Fri, 15 Jun 2001 08:21:17 -0500
It depends on the project and the people. In some
cases, the doc people are developing the DTD. In
others, they are skilled and talented enough to
read the specs. You do have specs, right?
It just isn't that hard, and frankly, hiring a
technical writer with only typing, spelling
and Winhelp skills isn't that good a hire and
they will become boat anchors keeping the rest
of the organization behind the learning curve.
If you do have such, pay them like a secretary. When
the real secretary finishes the nighttime database course
(How hard is MS Access?), give the secretary
the higher wage and the technical writer's job.
Looks like a diagram to me, but maybe that is the
If a parser strips comments, get another parser.
Schemas have annotations, appinfo, and all of that.
Use it when you think you need the extra support.
Otherwise <!-- --> works in the interim.
This technology was originally designed to bridge
the chasm between the well-trained programmer and
the semi-computer literate. If it has been pushed
so far to the side of the programmer that the other user
can no longer decipher it, we have made a very big
mistake adopting XML.
Ekam sat.h, Vipraah bahudhaa vadanti.
Daamyata. Datta. Dayadhvam.h
From: XML Everywhere [mailto:email@example.com]
A DTD is a contract. If a DTD is
in flux, the doc people should
not be involved until later
in the development cycle. Otherwise,
devs and docs are both going to
Developers should write the initial
documentation for DTDs,
not doc people. Doc people
can make the docs pretty,
clean up grammar, and provide
examples. Describing a DTD to
a doc person verbally (or worse,
handing them an undocumented
DTD) is generally not very effective. Just try
that with HTML. It's just tag
soup and unless the doc
person has access to the
application (e.g., a browser),
DTDs are pretty difficult
But generally the docs that developers write aren't
very easy to follow. Once the DTD is
finalized, doc people can do a lot
in making the documentation easier
to understand, mainly via examples.
As far as tools go, I don't think
XML Spy can graphically
represent DTDs (at least I
haven't found that feature).
Extensibility (or whatever name
its new owner gave it) does.
XML Spy does show XSDs graphically.
I believe XSDs support comments and
annotations directly in the model.
DTDs require text to be added
in XML-style comment blocks (<!-- -->)
and there are lots of places
where parsers don't allow comments,
which is a pity. So with DTDs you are almost always
forced to make the documentation
external. We put the documentation
in HTML format.