[Box Backup-dev] [Doc] Format of the documentation

[Ben Summers]

On 27 Feb 2006, at 06:21, Per Thomsen wrote:

> Documenters,
> I think the first thing we need to decide is what format we should use
> for the documentation, and then get the existing docs (fluffy.co.uk  
> and
> the Wiki) into that format. I have looked at DocBook, and it looks  
> like
> it would fit our needs.  It would be easy to get DocBook files into  
> svn,
> and the HTML generated looks OK.

For the web site, it might be nice to use the existing look. This may  
require a simple script to process the output of whatever you choose,  
or you could write it as HTML fragments which get turned into the  
read pages. I have a number of scripts which will help.

>
> Let me know what you think. I'd like to get started ASAP, with  
> figuring
> out the outlines for the books we need to produce.
>
> I'm going to be going over the Wiki and Ben's web site, to see if I  
> can
> categorize the pages (or even sections) into the books they belong in.

It would also be nice to have manual pages for the executables as well.


>
> Also, we need to figure out how the docs will fit in svn. Should  
> they be
> a seperate project in svn? Like http://bbdev.fluffy.co.uk/svn/ 
> boxdoc  ?

I think it would be good to put it within the existing repository.  
This allows the documentation to be kept in sync with releases  
easily, and for the documentation to be included in the release  
tarballs.

Once a format and arrangement has been chosen, we need to adjust the  
release scripts to include it, and depending on the format, run an  
appropriate pre-processor to make them readable.

I suggest

   [trunk|whatever]/documentation/boxbackup

as a location for the documentation. This is to preserve the idea  
that multiple distributions can be built from the same source tree.


>
> Lastly, I don't think there is a problem, but I at least wanted to ask
> if it is OK to use the -dev list for any discussions relating to the
> documentation. Most of the editing will be passed back and forth  
> through
> svn, so the list would be used for discussions. Let me know if we  
> should
> find a different forum for discussing the documentation.

I would encourage the use of -dev, so that documentation is always  
linked to the development work. The two should not be isolated, in my  
opinion.


Thank you for organising this documentation effort. This is just as  
essential as the code itself.

Ben