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?
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.
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.
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.
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.
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.
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:
Other huge advantages are:
Long term advantages:
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!
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.
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).