DTDs for Internal IT Documents?

Saqib Ali asks: "A DTD (Documentation Type Definition) defines the document structure with a list of legal elements. DocBook DTD is being widely used in creating Linux related documentation. However I am looking for a XML DTD that is more suited to internal IT documentation, and easy to learn and use. Preferably I would like to use a DTD that can be used with OpenOffice. What DTDs are other Slashdot readers using for for internal IT documentation? I have created documentation using DocBook DTD and hosted them on a Apache Cocoon . Cocoon lets me transform the XML to HTML or PDF. I would like to keep the same backend infrastructure (i.e. Cocoon) but try out other DTDs that are suited for IT related documentation. Any ideas?"

Comments

DTDs are pass

[Markus Registrada]

DTDs are '90s technology.

What you want is a Relax-NG Schema. DTDs only define the barest bones of XML structure. Validating against a schema lets you verify all kinds of things that a DTD can't even express.

(Don't be confused by W3C Schemas. That format stinks.)

Is a schema important for documentation? It depends on how much structure you need, which largely depends on how many uses you have for the documents. My employer actually puts the documentation itself in the schema, and generates manuals from the same text that validates important input files.

Re:DTDs are pass

[Mr. Piddle]

What you want is a Relax-NG Schema. DTDs only define the barest bones of XML structure. Validating against a schema lets you verify all kinds of things that a DTD can't even express.

(Don't be confused by W3C Schemas. That format stinks.)

This is why XML still sucks. The technology is volatile, even down to the schema format!

So, even after several years of not knowing what to focus on to learn how to use XML effectively, I still wouldn't know what to focus on to learn how to use XML effectively. Standard interchange my ass.

It's always a compromise

[ttfkam]

If you choose to make your own XML document schema, you lose out on the preprepared stylesheets and converters. On the other hand, a schema made for the task at hand is usually easier to use and understand.

As a compromise, you might to check out the progress on XHTML 2.0. It has a syntax not too far removed from the HTML we've all seen before, but 2.0 is closer to the DocBook model of semantics rather than presentation. It is also more likely to be supported by 3rd party clients in the future. (There is already an XHTML 2.0 renderer available for Mozilla.)

Whatever you do, make sure the markup relates to meaning and NOT how it looks. Looks change, but if you don't take care to the meaning/semantics from the beginning, it is prohibitively difficult to put in in later. For example, it's easy to make all annotations and citations red. It's not so cut and dried to change all red text to annotations (when citations or emphasized text may be formatted in red).

Why, O Why?

[Gothmolly]

Is PDF too simple? Too cross platform? Too non-needing-its-own-application-infrastructure? It sounds like you have too much time on your hands. Concentrate on getting your tech people to document things, take whatever they'll produce, as long as it's better than:

foo=bar*.734 /*Fred says this needed to be here*/

Issues with today's XML editors

[Crayon Kid]

One thing I haven't seen much of is an XML editor which does real-time validation of the document against a DTD or XML Schema. The ones I've seen do only XML syntax (ie. well-forming) validation in real time, and syntax highlighting as a benefic side-effect. But you have to start the validation against DTD/Schema by hand (ie. push a button) and the feedback is in many cases raw output from the validator presented in a separate pane or window. What I'd like is the highlighting to give me useful feedback the split second I stray off of the DTD/Schema, as I type, with the additional more verbose messages in a separate pane.

Another issue I have with XML editors is their take on suggesting completion alternatives for the element or attribute currently under the cursor. Of course, most give you everything the DTD or Schema for the document has to offer. However, I'd like some kind of "most likely to be used" mode I can switch on/off and which will reduce the available completion set to the things that are most likely to be used for that particular document and position.

Re:DTD? No, I use XSDs.

[malachid69]

I think the thousands of acronyms that came along with XML has ruined a whole generation of computer science students.

Would you rather I had said this:

I don't use Document Type Definitions, but I do use Extensible Markup Language Schema Definitions for all of my document formats. There is a good link to learn the basics here.

I usually use Extensible Markup Language Schema Definitions with Java Advanced Programmer Interface for Extensible Markup Language Binding because it provides me with an Object-Oriented approach to reading/writing that specific format. There are also a couple projects to do that for C++ (Rogue Wave). Personally, I *love* Extensible Markup Language Data Binding, because I no longer have to deal with Document Object Model or Simple Advanced Programmer Interface for Extensible Markup Language.

Realistically, these acronymns are the only thing that make our posts even readable/understandable.