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

Why not Docbook?

[molo]

Is there some reason why Docbook is insuffient? More info at www.docbook.org.

-molo

Re:Why not Docbook?

[Rheingold]

1. How about Simplified Docbook?
2. Aside from its own document formats, DocBook is the only format OOo supports, AFAIK, so if that's important to you DocBook is the only option.
3. I don't really know of any WYSIWYG editors that support anything else that's XML-based.

In summary, I don't think there's a better solution than DocBook, despite the fact that it does not fulfill all of your requirements.

Skip XML for source.

[FFFish]

Use ReST (ReStructured Text) and DocUtils. DocUtils outputs perfectly nice XML (ignore the HTML, LaTeX, and other options). It's then easy enough to use XSL:FO and FOP/XEP to transform the XML to PDF.

Been using it for a year, and I'm absolutely flippin' delighted with it. Structured documentation that's both open-standard and imminently readable, yet delivers great PDFs.

Re:Why, O Why?

[stonebeat.org]

Structure Documents. Structure Documents has it is own benefits:
# "Write Once, Publish Anywhere" - You have only to prepare single documents; you can either use them as they are with stylesheets or convert them later to different physical media and formats, including plain text, XHTML and PDF.
# Since your documents are in non-proprietary text format, you can edit them with any text editor, and assure their continuity and cross-platform compatibilty.
# The physical layout of documents is separated from the content.
# Retrieving specific information is very esay from structured document.

Too close to home.

[Trejkaz]

The company I'm working for are currently working on a "business narrative markup language" which is intended to be an overly simple markup for writing business documentation. I think it's going fairly well, though without a trial in the real world it's hard to say.

The main problem we found with XHTML were a complete lack of useful structure (e.g. in XHTML2 you can have plain text inside a section, or a paragraph inside a section with plain text inside the paragraph, or <l> elements inside the paragraph with plain text inside the paragraph. Three different ways to mark up exactly the same thing. If you don't know why that is bad, try to write an XPath which selects the first line of text of the first section in the document.

The main problem we found with DOCBOOK is that there are far too many elements for any mere mortal to learn, and we wanted a secretary to be able to understand our language. By contrast, ours achieves most of its structure through nested items, and blocks of text (effectively paragraphs.)

There are also groups in OASIS trying to nail exactly this sort of thing but XHTML2 is being a fairly big pressure, to say the least.

On a related topic...

[Trejkaz]

A "roll your own" approach works quite well. Assuming you only need a small number of features, you could either just devise a small set of elements to do the job, or you could devise an outer structure and include XHTML or XHTML2 as the content of sections in that structure.

This is the way I'm working on the development weblog I've been rolling. If I need a new element to bring in more semantics, I invent it at the time I need it. Since nobody else needs to use the content, and XSL does all the presentational transformation, this approach works quite well.