Over to you on documentation systems

From time to time someone asks me for a little advice. That was the case 
when Róbert 
Gál got in touch about finding the ideal documentation system.

We have a problem right now. We urgently need to find a documentation system
 that meets the following requirements.

• Team use, with several people editing at once
• Easy editing, quick and accessible
• Easy searching, with full text and wildcards
• Export to HTML and PDF
• CVS support so we can edit away from work, offline
• Cross-references
• Extensibility and support

All we’ve found is DocBook, but that’s only the foundation.
 Add an open-source editor and CVS, and it’s still nothing special…
 Can you recommend anything? What do you use there?
 I also found TWiki, which meets all the requirements above
 but stores its data in a database like any wiki. XML would be better.

We looked at wikis such as TWiki, which met our requirements, 
but I couldn’t find an XML-based system. Every wiki keeps its data in a database, 
usually in a format of its own.
So we agreed on DocBook, like you did.
We’ll synchronize through CVS.
There are still two problems to solve.

Easy full-text and wildcard search

We’ll probably have a server generate HTML files from DocBook
on a regular schedule, maybe every 30 minutes. That’s easy enough with
Maven and the sdocbook plug-in, for example. 
Then it looks as if we’ll use the Eclipse help system to build a nice help site
out of those HTML files. It would look like http://help.eclipse.org/help30/index.jsp
(see also http://www-106.ibm.com/developerworks/opensource/library/os-echelp/)

The documentation generated in the Eclipse help system would even be easy to
integrate into Eclipse itself, so a developer could read company documentation
right there. More likely, though, we’ll make the documents available at
an internal URL.

Easy editing, quick and accessible

There are several possible solutions to the second problem.
To edit DocBook we’ll use an open-source WYSIWYG editor,
whose name I can’t remember, or OpenOffice.
It’s a shame there’s no graphical DocBook plug-in for Eclipse. That surprised me.
Any ideas for editing DocBook quickly, so we can make the learning curve
as gentle as possible for the whole team?

I think CVS and DocBook are a straightforward choice. A minor drawback 
is DocBook’s steeper learning curve for most users, unless they already write HTML or XML. 
On the other hand, 80% of documentation can be written with a handful of elements, paragraphs, lists, headings and chapters, images, links, quotations and so on. Anyone can pick those up. 
It’s more a matter of getting the whole team to agree to use DocBook 
as the documentation tool.

At our company, DocBook is the standard for information system documentation. Everyone writing the specifications had to 
move from Word to DocBook. We supported them with training and a customized editor for writing documentation. It runs batch scripts for validation, spellchecking and generating the output. The editor is EditPlus, so it’s no WYSIWYG tool. We also have internal material on writing in DocBook, essentially a help guide.

Coming back to the editor, I think it’s hard to find a good, affordable 
WYSIWYG DocBook editor. It was when we moved to DocBook, at any rate. Looking now at the support 
in OpenOffice, what it calls WYSIWYG is worlds away from what I have in mind. It seems that anyone writing documentation in OpenOffice would still need to know DocBook’s structure to create a document at all.

I like the idea of generating documentation with Maven. Any automation helps. I’d set aside 
one production documentation server and automate the whole process there, from fetching and generating to packaging and publishing. For search, 
Google Desktop Search springs to mind. I’d install GDS on the production documentation server to make search available to everyone. The drawback is that it only runs on Windows. On other platforms I’d choose 
something like Lucene, an idea I got from Dion Almaer’s article I love Lucene.

Related articles

• (14 June 2004, Dagblog) Czech DocBook site launches
• (12 November 2003, Dagblog) DocBook puts documentation at your fingertips