You can download the ZIP file at:
https://docs.oasis-open.org/docbook/docbook/v5.2/csd01/docbook-v5.2-csd01.zip
"Send A Comment" at (https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=docbook). #docbook
ChatGPT is the latest rage in AI. I thought I'd put it to the test, so I asked it: Explain DocBook vs DITA.
Here is the response:
ChatGPT: DocBook and DITA (Darwin Information Typing Architecture) are both markup languages used to create structured content for technical documentation. While they share some similarities, they have distinct differences in their approach to document creation and management.
DocBook is a general-purpose markup language that can be used to create a wide range of technical documents, including books, articles, and manuals. It was developed in the late 1990s and is maintained by the DocBook Technical Committee, which is part of the OASIS (Organization for the Advancement of Structured Information Standards) consortium.
In contrast, DITA is a specialized markup language designed specifically for creating technical documentation. It was developed in the early 2000s by IBM and is now maintained by the OASIS DITA Technical Committee. DITA focuses on creating modular, reusable content components that can be assembled into different documents.
One of the main differences between DocBook and DITA is their approach to content reuse. DocBook provides some support for content reuse through its use of entities, but it is not as comprehensive as DITA's reuse mechanisms. DITA uses a topic-based approach, where each topic represents a modular, standalone unit of content. These topics can be combined and reused across different documents, making it easier to maintain consistency and reduce duplication.
Another difference is their support for different output formats. DocBook has broad support for a wide range of output formats, including HTML, PDF, and EPUB. DITA also has good support for different output formats, but its focus on modular content means that it is best suited for online help systems and other types of documentation that can be assembled dynamically.
In summary, while both DocBook and DITA are markup languages used for technical documentation, they have different approaches to content creation and management. DocBook is a general-purpose markup language, while DITA is specialized for creating modular, reusable content components. Both have their strengths and weaknesses, and the choice between them will depend on the specific needs of your documentation project.
My response: DocBook v5.0 introduced the concept of Assemblies, which resemble DITA Maps, and a topic type which enables stronger reuse capabilities, similar to DITA.
ChatGPT: Yes, that is correct. In DocBook v5.0, the concept of Assemblies was introduced to improve the management and reuse of content. Assemblies are similar in concept to DITA Maps, allowing authors to create collections of topics and arrange them in a hierarchy to build larger documents.
Additionally, DocBook v5.0 also introduced a new topic type, which allows authors to create reusable content modules that can be used in multiple documents. The new topic type provides stronger reuse capabilities, similar to the topic-based approach used in DITA.
These changes in DocBook v5.0 were designed to address some of the limitations of earlier versions of the markup language, particularly in the area of content reuse. By adopting some of the best practices and concepts from DITA, DocBook has become a more flexible and powerful tool for technical authors and publishers.
My response: Which is better?
ChatGPT: There is no definitive answer to which is better between DocBook and DITA, as the choice between the two depends on a variety of factors such as the specific needs of the project, the skillset of the team, and the intended audience.
DocBook is a general-purpose markup language that can be used for a wide range of technical documentation, including books, articles, and manuals. It has a wide range of output formats and a large user community, making it a good choice for projects that require a lot of flexibility and support.
DITA, on the other hand, is specifically designed for technical documentation and is highly modular, making it a good choice for projects that require a lot of content reuse and maintenance. It also has strong support for online help systems and other dynamic output formats.
Ultimately, the choice between DocBook and DITA will depend on the specific needs of the project and the preferences of the team. It's worth evaluating both options and selecting the one that is best suited for the specific needs of the project.
I found the responses quite accurate and interesting! Radu at oXygen also had an interesting experience with ChatGPT: https://blog.oxygenxml.com/topics/using_chatgpt_in_a_dita_xml_project.html
My latest article: Standards within a Standard http://t.co/kJSIBauWqF
— Scott Hudson (@shudson310) March 10, 2015This past Friday I was honored by the Colorado State University Department of Technical Journalism as part of the 2nd annual Alumni Media Festival.
Out of about 150 entries, about 25 "Cammy Award of Excellence", 10 "Cammy Grande" awards, and 4 Best of Festival awards were given out. Entries spanned Broadcast, Newswriting, Public Relations an Technical Writing. Each entry was judged on a 0 to 100 point scale.
At the last minute, I decided to enter the specification for the DocBook Schema for Publishers, which finally achieved OASIS Committee Specification status this past August. The entry scored 100 points and was awarded a "Best of Festival" award!
 |
| Department Chair Greg Luft presenting me with the award |
 |
| A proud Ram and his awards |
 |
| Best of Festival Award |
I'm very happy to announce the formation of the DocBook Subcommittee for eLearning! The DocBook Technical Committee approved the subcommittee and following charter on 21 Oct 2009:
For more than a decade, DocBook has provided a structured markup vocabulary for hardware and software documentation. DocBook is now widely used in both commercial and Open Source environments. DocBook has a very broad element set, and applies to much more than just technical documentation. The DocBook TC is engaged in evolving the suite of DocBook specifications. The community benefits from having a standard, open, interchangeable vocabulary in which to write structured content. DocBook has been, and will continue to be, designed to satisfy this requirement.
The OASIS DocBook SubCommittee for eLearning is chartered to develop and maintain official variants of DocBook in support of the eLearning industry. Specifically, the subcommittee will focus on schema and stylesheet customizations to support:
This subcommittee will submit additional enhancements back to the full DocBook standard as appropriate. The scope of this DocBook subcommittee is eLearning content. Broadly, this includes online learning, instructor-led training and other related educational materials.
This effort will deliver on the following goals:
We already have 5 members, who are very eager to get started! If you are an OASIS member and would like to participate, please let me know!
I've just been accepted to present at XML-in-Practice 2009, September 30 - October 1, 2009 at the Arlington Hilton near Washington DC!
My presentation entitled, Professional Publishing on a Shoestring Budget, will discuss how to optimize your multi-channel publishing processes using the latest approved DocBook v5.0 schema and the DocBook Publishers schema.
Details on the conference are available at the XML-in-Practice website.
I hope to see you there!
Well, we finally got all the i's dotted and the t's crossed! The DocBook Publishers schema is available for public review. This is an effort I chaired to support the needs we've seen in the publishing industry.
Many publishers spend considerable amounts of time and money developing and maintaining their own custom schemas and output rendering. This standard tries to address the unique needs of publishers, while building upon a standards-based platform to reduce cost and ensure consistency. Key publishers involved in this effort have included: O'Reilly, John Wiley and Sons, and Penguin UK, so this was not developed in a vacuum either!
Here's the notice from OASIS:
The OASIS DocBook TC has recently [January 2009] approved the following specification as a Committee Draft and approved the package for public review:
The DocBook Publishers Schema Version 1.0
The public review starts today, 2 July 2009, and ends 31 August 2009. This is an open invitation to comment. We strongly encourage feedback from potential users, developers and others, whether OASIS members or not, for the sake of improving the interoperability and quality of OASIS work. Please feel free to distribute this announcement within your organization and to other appropriate mail lists.
More non-normative information about the specification and the technical committee may be found at the public home page of the TC at: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook. Comments may be submitted to the TC by any person through the use of the OASIS TC Comment Facility which can be located via the button marked "Send A Comment" at the top of that page, or directly at: http://www.oasis-open.org/committees/comments/index.php?wg_abbrev=docbook .
Submitted comments (for this work as well as other works of that TC) are publicly archived and can be viewed at: http://lists.oasis-open.org/archives/docbook-comment/. All comments submitted to OASIS are subject to the OASIS Feedback License, which ensures that the feedback you provide carries the same obligations at least as the obligations of the TC members.
The specification document and related files are available here:
Editable Source:
http://docs.oasis-open.org/docbook/specs/publishers-1.0-spec-cd-01.xmlPDF:
http://docs.oasis-open.org/docbook/specs/publishers-1.0-spec-cd-01.pdfHTML:
http://docs.oasis-open.org/docbook/specs/publishers-1.0-spec-cd-01.htmlSchema:
http://docs.oasis-open.org/docbook/rng/publishers/publishers.rncOASIS and the DocBook TC welcome your comments.
You can also take a look at all of our content samples on SourceForge here:
http://docbook.svn.sourceforge.net/viewvc/docbook/trunk/docbook/relaxng/publishers
Nominations are open until May 29th. Please vote for DocBook in the Best Project for the Enterprise category. If you want to do the same, click here!
Get the word out using your social network and vote!
A few weeks ago, I found an interesting article on gauging the success of Open Source projects. Since I contribute to several open source and standards initiatives, I thought I'd put the article to the test with the most prominent of these: DocBook.
To give a little history, DocBook has been around since 1991. It is a very robust content model and considered the "de facto" standard for technical documentation. Given it's broad adoption, does that necessarily mean it is successful? Why? The article provides a 9-point checklist, so I'll address each of these in turn.
A thriving community - DocBook has one of the most active user communities around. Don't believe me? Check out the docbook-apps mailing list and the docbook mailing list and by tuning into the DocBook irc channel. You can get expert help from around the world almost 24-7 and in multiple languages, too! Many of these are contributors to the DocBook project on sourceforge.net, and participation is welcomed and encouraged.
Disruptive goals - Many would agree that DocBook provides much more control and semantics to what is currently available in Microsoft Word or other commercial documentation solutions. DocBook aims to be the preeminent solution for creating books and papers about computer hardware and software (though it is by no means limited to these applications).
A benevolent dictator - Two words: Norm Walsh. Norm is very well known in the XML community. He is not afraid to speak his mind concerning requested features, but is very open to new ideas and contributions.
Transparency - DocBook is maintained by a technical committee at OASIS. All activities and correspondence is archived and available for public review and input. The DocBook mailing lists are also archived by several different services. You can't get much more transparent than that.
Civility - This has never been an issue in the DocBook community. All participants are very professional, and willing to help the newbies as well as experts with any DocBook-related issues.
Documentation - Not only is the DocBook specification publicly available, but Norm Walsh has open-sourced his book, "DocBook: The Definitive Guide" and Bob Stayton has open-sourced his book, "DocBook XSL: The Complete Guide". These are the best sources of documentation available for DocBook, but several parameter references as well as the DocBook wiki are also publicly available.
Employed developers - While DocBook does not have any official paid developers, several of the contributors work full-time on DocBook and DocBook implementations.
A clear license - The standard is freely available from OASIS as well as the docbook.org site. The specifications are covered under OASIS IPR Policy, where you can read all of the details.
Commercial support - Last, but not least, DocBook is supported in many commercial products.
In consideration of these 9 items in the checklist, I would posit that DocBook is, indeed, a very successful open-source project and well worth considering for your documentation.
I'd also like to point out to the naysayers that DocBook is NOT dead! In fact, it is more active than ever! The latest version of the standard (v5.0) has been in development for the last several years and is expected to reach official OASIS standard status some time this year. The DocBook TC is also establishing subcommittees to address industry-specific needs.
The first of these is the DocBook Publishers subcommittee, which is addressing the needs of the publishing industry (as opposed to computer hardware and software documentation industry). The specification for an official Publishers schema was recently approved and will be available for public review shortly.
If you have specific needs in publishing, documentation, or content management, we would be very pleased to assist you. Please visit the new Flatirons Solutions website at: http://www.flatironssolutions.com
I'm proud to announce that the DocBook Publishers SubCommittee presented the specification for the DocBook Publishers schema to the DocBook Technical Committee. In the meeting, the motion to approve the specification to DocBook TC Working Draft was carried!
So what does this mean?
Prior to this, the specification was "locked up" in the subcommittee as it was being developed. Now that it is an official DocBook TC Working Draft, it will be available for public review for the first time! We would appreciate any and all feedback! I'll post a link as soon as it's available.
This specification would not be possible without the diligent work of:
We hope this specification will make it easier for the publishing industry to produce multi-channel content from DocBook XML!
For those of you interested, I've set up a DocBook group on Plaxo (http://docbook.plaxogroups.com/) and LinkedIn. Please join if you are interested in DocBook or in networking with DocBook professionals!
Jim Earley has a very thoughtful post on metadata interoperability: http://jims-thoughtspot.blogspot.com/2008/04/metadata-interoperability.html
As part of DocBook v5, we added the ability to include content from other namespaces in the <info> block to support adding Dublin Core directly in your content. The <info> element's purpose is to house metadata that is not intended for display, so it's a really good fit.
Jim's argument, is that the various standards out there (DocBook, DITA, ODF at a minimum) should move to Dublin Core for metadata, and stop re-inventing the wheel. Dublin Core is an internationally accepted standard for metadata, so why not use it directly?!
I whole-heartedly agree. This approach would add more compatibility between standards, and maybe even facilitate better search! Along with that, Dublin Core is extensible, so it shouldn't be too difficult to add additional metadata fields if you need to.
Teresa Mulvihill has written an article on DocBook vs. DITA at: http://www.dclab.com/dita_docbook.asp.
It's a well thought-out article, but I'd like to make a few clarifications:
As you may know, Jim Earley and I have presented on this topic and our Doc Standards Interoperability Framework at several conferences, and still hope to form an OASIS TC on document standards interoperability.
In the article, Teresa states:
"DocBook is hierarchical by nature, and must be developed to allow for single-sourced content. DocBook has a fixed element and attribute set."
I've successfully used and recommended single-sourcing approaches with DocBook, without additional development. It's quite easy to set up a book or article and use XIncludes or even file entity references to pull in content from a common pool of content structures (usually section or chapter).
It's also fairly easy to extend the elements and attributes in DocBook. This has been made even easier with DocBook v5.0 and RelaxNG. In fact, the DocBook Subcommittee for Publishers that I chair, has helped organize the source patterns for DocBook v5 with a modular approach, enabling easier customizations to be created. Our subcommittee has created a customization geared specifically to publishers, without all of the technical blocks and inlines in full DocBook. This significantly reduces the tag set for folks that do not produce software or technical documentation to use the DocBook standard for general publishing!
DocBook can generate more than PDF, HTML and HTMLHelp. The docbook-xsl-1.73.2 stylesheet distribution supports: html, htmlhelp, javahelp, manpages, xhtml, Word roundtrip, slides and websites!
I would also argue that DocBook can be used on very high volume documentation projects, as well as small and medium projects. Just ask Sun, HP, various Linux distros, and more listed here: http://wiki.docbook.org/topic/WhoUsesDocBook
You might also find Norm's blog on DocBook vs. DITA interesting: http://norman.walsh.name/2005/10/21/dita
We are also working on some exciting developments for the Interoperability Framework, so stay tuned!
The Content Wrangler has published a very interesting article by Dick Hamilton on choosing an XML schema.
I get asked very similar questions all the time! I think I'll start sending folks to this article as recommended reading...
I'm pleased to announce that DocBook v5.0 is now an official Committee Draft! The schema can be downloaded here: http://docbook.org/xml/5.0/.
This is the result of several years work. Special thanks to all of the Committee members involved:
* Steve Cogorno, Sun Microsystems
* Gary Cornelius, Individual
* Adam Di Carlo, Debian
* Paul Grosso, Arbortext
* Dick Hamilton, Individual
* Nancy Harrison, IBM
* Scott Hudson, Individual
* Mark Johnson, Debian
* Gershon Joseph, Tech-Tav Documentation Ltd.
* Jirka Kosek, Individual
* Larry Rowland, Hewlett-Packard
* Michael Smith, Individual
* Robert Stayton, Individual (Secretary)
* Norman Walsh, Sun Microsystems (Chair, Editor)
Next step: OASIS standard!