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

[Per Thomsen]

On 2/27/06 3:40 AM, Ben Summers wrote:
>
> 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.
Right. I believe there are ways of 'skinning' docbook conversion to
HTML, to make it look like we want. Some added benefits will be improved
navigation controls, etc.
>
>>
>> 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.
That's a good idea. A bit of googling tells me that you can create
man-pages from docbook as well, without any fuss.
>> 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.
OK.
>
> 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.
Sounds good. Do I need special privileges to check into svn?
Username/Password?
>> 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.
I agree. I just wanted to make sure, as the list is already pretty
high-volume.

Thanks,
Per

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