Re: DOCBOOK-APPS: Best authoring environments for publishing thousandsof Web pages in XML

[Bob Stayton <bobs at sco dot com>]

On Fri, Feb 21, 2003 at 11:20:36AM -0800, Katherine Hostetter wrote:
> I'm creating a presentation on XML, XML tools, and issues that we'll likely
> be dealing with if we convert thousands of Web pages to XML. (Currently our
> tags are based on the SGML DocBook. We use Lotus Notes for the database,
> conversion to HTML, and the authoring environment.)
> 
> Our company also produces software manuals, training, and other paper
> documents. We're going to content management and single sourcing, and have
> purchased Interwoven for e-commerce. Our company has many decisions yet to
> make in this process, but knowing something about what others have done
> should help us all "land on our feet" when changes are made.
> 
> A big concern for writers and editors is what the future authoring
> environment might be. How do others work with the many elements in DocBook?
> Do you "load" only certain sets of elements at a time? Do you have an
> interface--like that for HTML--which has tags to select? Do you have a
> content structure that authors must use? Is DocBook incorporated into a
> form so that authors aren't doing any tagging? Do you use an interface that
> you created, or one that
> you purchased, such as XMetal?

I can tell you what we use for XML-based documentation.  I
imagine this is a pretty common setup.

We keep the XML source files on a Linux system in CVS.  We
let our authors export their working CVS directory as a
Samba share.  The authors map that share as a network drive
on their Windows desktop system.  They write and edit the
files with XMetal on the Windows box.  We have found that
despite some quirks, XMetal provides a usable interface for
writing DocBook.  Some training about tag selection is
necessary, of course.  But you can also have it display
only 'Used' tags rather than 'All' tags, so that 90% of the
time you are selecting from a short list.  The author saves
the file, which writes it back to the Linux box, where they
have a separate ssh window to check in the changes.  We
have a Makefile for each book that they can execute to
generate HTML or PDF output for test builds.  The same
Makefile is used by the nightly build to create the
product.

This setup lets the authors concentrate on writing.
They are technically savvy enough to tweak the 
Makefiles that I originally wrote for them.
XMetal ensures that the files are valid, so we have
very few problems with the nightly builds.
-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs at sco dot com