[Box Backup-dev] Re: [Box Backup] Documentation writing tools

[Per Thomsen]

On 8/11/06 1:46 AM, Ben Summers wrote:
>
> On 11 Aug 2006, at 01:20, Per Thomsen wrote:
>
>> The instructions are on the Wiki:
>> http://boxbackup.hostworks.ca/index.php/DocProject
>>
>> Briefly: Documents are created in DocBook, using XMLMinds free (beer)
>> version of XXE, and checked into SVN. A baseline of docs (mostly
>> gathered from the Wiki) have been created, but some of the books
>> could do with some TLC.
>>
>> To make the documents from the DocBook sources, xsltproc is needed.
>
>
> XML isn't too difficult to write by hand. Is it sensible to try
> editing them by hand and getting someone else to check they validate
> properly?
>
> I'm just wondering how the barrier to participation can be reduced.
Moving to '-dev'...

The problem with writing the DocBook by hand is, as you mention, the
validation. While I think it's fine to hand-edit the XML, the DTD rules
are quite complex for DocBook, and I've found that debugging a flawed
document when hand-editing can be quite tricky. XXE takes care of that
completely. Even though XXE is WYSIWIG, using it can feel awkward at
first, I readily admit, and if there is a tool that works better for
you, it's fine to use it, as long as it generates valid DocBook XML.
That said, XXE was easy to install. It took about 10 minutes to get
going for me.

Xsltproc is quite simple to download and install, and it appears that it
is preinstalled on some Linux distros. I checked Ubuntu and FC5.

WRT xsl-docbook 1.69.1, you can get by without using it, but if you're
editing man-pages, you will quickly grow annoyed with 1.68.1. On Fedora,
I simply installed the 1.69.1 RPM over the 1.68.1 one, and there were no
conflicts.

Based on the discussions on the list, I will be expanding the
instructions on the Wiki, to hopefully ease the minds of those
overwhelmed with the amount of stuff to learn when starting with DocBook.

In conclusion, the use of DocBook (as opposed to POD, or other formats)
might be the biggest barrier to entry for potential contributors, but I
feel strongly that the flexibility we gain by using it, gives us the
right set of tools to create the best and most relevant documentation we
can.

If there are other ideas to how we can get more people to help, I'm
eager to hear them.

Thanks,
Per

-- 
Per Reedtz Thomsen | Reedtz Consulting, LLC | F: 209 883 4119
V: 209 883 4102    |   pthomsen at reedtz.com  | C: 209 996 9561
GPG ID: 1209784F   |  Yahoo! Chat: pthomsen | AIM: pthomsen