| When it comes to documentation projects, | | | | |
| primarily technical, medical, and scientific, | | | | Docbook: regular XML file called an include |
| using XML is a no-brainer. The heavy thinking | | | | file with all files included in the document |
| comes when deciding which flavor of XML to | | | | |
| use: DocBook or DITA (Darwin Information | | | | DITA: ditamap file with all files and each |
| Typing Architecture). I have been a steadfast | | | | file's related links |
| supporter of DocBook for over six years. I'd | | | | |
| tried my hand at DITA and gave it up as a | | | | 7. Output |
| fad; lots of bells and whistles, but too | | | | |
| complicated to integrate. And couldn't | | | | Docbook: PDF, HTML, HTMLHelp |
| DocBook do everything DITA promised anyway? | | | | |
| | | | DITA: unrestricted, but all need development |
| So when Allette Systems contacted me to speak | | | | |
| on XML standards in SydneyAustralia, I jumped | | | | 8. Community |
| at the chance to prove to the documentation | | | | |
| world just how wonderful DocBook is and how | | | | Docbook: well supported by the XML community |
| DITA falls short. Fortunately, my in-depth | | | | |
| research opened my eyes to the benefits and | | | | DITA: small but strong, growing community |
| limitations of both. | | | | |
| | | | 9. Complexity |
| In a nutshell, DocBook has the advantage of | | | | |
| age; it's stable, easy to setup, and created | | | | Docbook: with a little development, DocBook |
| for technical documentation publications. | | | | can do what DITA is attempting on a smaller |
| While DITA has the advantage of youth; it's | | | | scale |
| innovative, complete with its own | | | | |
| architecture, and created for documentation | | | | DITA is impressively engineered, but can be |
| outside the book. DocBook was hatched in 1991 | | | | too industrial-strength |
| by HaL computer Systems and O'Reilly. In | | | | |
| 1998, Oasis gave DocBook its own technical | | | | 10. Possible Needs |
| community. A year later, DITA began evolving | | | | |
| from cross-department teams within IBM. Its | | | | Docbook: Content Management System |
| Oasis technical community was established in | | | | |
| 2004. | | | | DITA: Publishing plug-ins |
| | | | |
| My research and experimentation with these | | | | DocBook is well supported, easy to integrate, |
| two standards is summarized in the following | | | | and tailored to technical documentation |
| table. | | | | needs. DITA has a highly technical, |
| | | | innovative community, can (with development) |
| 1. Definitions | | | | publish to all online formats, and comes with |
| | | | its own architecture (content management). |
| DocBook is a document type definition (DTD) | | | | |
| for writing technical books and articles, | | | | So how do you decide? Well, the good news is |
| with the structure that such forms imply. | | | | DocBook and DITA are quite similar in basic |
| | | | elemental parts and XML tags. For example, |
| DITA is both a DTD and a set of rules for | | | | DocBook is built on sections, which can be |
| writing online contextual documentation such | | | | compared to DITA's topics, as shown in the |
| as software help files. | | | | figure below (see image at |
| | | | |
| 2. Concepts | | | | Why is this good news? Because smaller |
| | | | companies, or those new to XML, you start |
| DocBook is hierarchical by nature, and must | | | | with DocBook and graduate to DITA when and if |
| be developed to allow for single-sourced | | | | needed. |
| content DocBook has a fixed element and | | | | |
| attribute set. | | | | Online communities (Oasis Open Document) and |
| | | | companies (Flatiron Solutions) are already |
| DITA separates content from context, allowing | | | | attempting to facilitate compatibility |
| multiple architectures of information DITA is | | | | between these two standards. |
| extensible, allowing the definition of | | | | |
| information types | | | | The table below may help you decided which |
| | | | standard is right for you and your company |
| 3.Context | | | | today. |
| | | | |
| Docbook: book (section) oriented | | | | 1. Documentation volume |
| | | | |
| DITA: topic oriented | | | | Docbook: small and medium |
| | | | |
| 4. Key Features | | | | DITA: large |
| | | | |
| Docbook: large set of elements and attributes | | | | 2. Documentation output |
| targeted for technical documentation | | | | |
| | | | Docbook: PDF, HTML, HTMLHelp, others with |
| DITA: topic based, separation of content and | | | | development |
| context, specialization | | | | |
| | | | DITA: all with development |
| 5. Download and Installation | | | | |
| | | | 3. Basic integration time frame (no |
| Docbook: bat, bin, dtd, etc. files and eDE | | | | conversion) |
| able to run with as is | | | | |
| | | | Docbook: one business day |
| DITA: bat, bin, dtd, etc. files, and | | | | |
| transformation engine | | | | DITA: one month plus |
| | | | |
| 6. Document File | | | | 4. |