views:

784

answers:

8
+9  Q: 

Who uses DocBook?

Hi there. I was wondering what people use for Documentation and saw that this had already been asked here

There seemed to be a lot of votes for LaTeX, I'm an advocate of LaTeX over Word due to its WYGIWYW (What You Get is What You Want) approach. However, its not easy to convince others to use it.

I'm inertested to hear from anyone who has successfully convinced their team to use DocBook for documentation?

+6  A: 

We used to use it. It's hard if you have non-technical users in your team. We bought an Epic Editor license but in the end, Word was still easier. Plus it was a PITA to customize the DocBook output. It can be done, but the cost (in time) wasn't worth the benefits for us.

Roel
This has been my experience too (sorry, no votes left today). As long as programmer-types are writing the docs, DocBook is great, but other people will fight tooth-and-nail against any requirement to use it.
Kristopher Johnson
+6  A: 

I've not used DocBook as part of a team, but for writing my own articles. I've seen quite a bit of documentation written in DocBook as well.

While it is difficult to do for non-technical people, it's still loads easier than using some form of TeX. Also, it's been getting simplified with each newer release, and the XSL Stylesheets are a great way of getting output in various formats (DocBook XSL: The Complete Guide by Bob Stayton is all but a required resource to make the most of them, although the defaults are pretty good).

When it comes to writing documentation, unless it is something incredibly simple, I'd choose DocBook over all others.

Chris Charabaruk
+1  A: 

I maintain a project where I wanted to produce printable/viewable documentation as well as the on-line help from the same source. I originally tried this with texinfo but always struggled to get compilable help from it. When I found out that docbook had the ability to produce htmlhelp as well as fo (which can be easily translated to pdf), I started using it and have been mostly pleased with the results.

Jon Trauntvein
+2  A: 

If you want to take a look at real-world in-project references, Hibernate and Spring serve well as rolemodels to learn how to integrate Docbook in your build e.g.

Oliver Gierke
+2  A: 

All Sun's documentation is based on DocBook. (Or actually, to be more precise, it's based on SolBook, which is a customization of DocBook.) If I remember correctly, then later versions of Solaris even had man pages in DocBook RefEntries rather than nroff. Also ActiveMQ's documentation is based on DocBook, and several publishers accept DocBook content.

Wilfred Springer
And I have to say that - while at Sun - I never wrote documents in anything else but DocBook. Once you get the hang of it, it's so much better than WYSIWYG. (WYSIWYG would have been fine if what I saw is actually what I wanted.)
Wilfred Springer
+1  A: 

We recently started using DocBook for generating the Release-Notes for the different products. The release notes document, is setup as a DocBook 'book' (one file). This file contains some general info and the XInclude references to the chapters (and optional the appendixes).

Each release version of the product, gets its own chapter (as a separate file). One of the sections contains the changes (of that release). The details of that section are extracted from BugZilla and placed in a separate file (in a directory target/docbook-generated). This section starts with an DocBook table which contains an summery off all the changes. Then for each row in the table, a detailed simple-section is followed. (We created a own Maven plug-in for this).

The release notes contain many times all kind of additional tables. The data in those tables is already available in different forms. So we created an other Maven plug-in which can convert csv based data into a DocBook table. Then the relevant data is easy to update / modify and they get automaticly included in the relevant chapter, as long as the table in reference correctly. (A warning / error is given when that happens.)

These csv tables, the chapter files and the release-notes file are all checked in along with the code of the project. This has several advantages, which developers see as obviously, but which are sometimes unknown to (technical) writers. Some are like:

  • easy checking of differences (good for reviewing new version of a book / article)
  • multiple users can edit / update the same document in parallel
  • branching of sources (SCM system)

Other huge advantages are:

  • Writers / developers can both update / add / correct the document (this was one of the problems we had)
  • Consistent look & feel, of the output document(s)
  • No time is wasted, with updating indexes etc etc
  • Automaticly building of documents (through Maven / Hudson) same as compiling code
  • Documents are close-by the product code (check-out as one project!) So no need to search for documents (easy to render by Maven target)
  • Easy inclusion of general sections like Copyrights, Legal stuff etc.
  • Easy included into the created installer (IzPack, as Maven plug-in)

Long term advantages:

  • If the house style of the company changes, only a few new style-sheet is required, and then all the documents, can be re-rendered (or will get the new style, as soon as the product is released again).

This is just a quick overview of what we did do. There is no real issue, why we should not use this for all our documentation.

It actually was the second time I did do this trick, to generate release-notes, with DocBook. It brings a lot of advantages and saves a lot of dull work for each release!

Verhagen
+2  A: 

Check out http://code.google.com/p/docbkx-tools/wiki/WhoIsUsingIt. It lists some of the projects and organizations that use the Maven plugin for generating output from DocBook documents. I think that's a pretty compelling list.

Wilfred Springer
A: 

Arbortext supports LaTeX natively. You can send the publishing engine or print composer LaTeX and it'll pass it through directly.

It also supports a lot of other composition languages as well and even gives the opportunity to do page-layout manipulation like you'd see in InDesign (without the headache and overhead of ID).

Liz Fraley