[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Bacula-devel] New manual format


On Wednesday 06 February 2008 19.33:39 David Boyes wrote:
> > Recently, I split the Bacula documentation (800+ pages) into the
>
> following
>
> > 7
> > documents:
> >
> >   Concepts and Overview Guide
> >   Installation and Configuration Guide
> >   Console and Operators Guide
> >   Problem Resolution Guide
> >   Catalog Database Guide
> >   Utility Programs
> >   Developers' Guide
>
> I'd suggest separating installation and configuration (they're really
> two very different problems),

Yes, I had considered doing that, but one of the goals was to try to get each 
manual below 300 pages.  The combined Installation and configuration is only 
244 pages, and the two subjects, though as you say are different, one 
immediately follows the other.  I wanted to keep the total number of manuals 
to a minimum without making any one of them too large.

> replacing the configuration part with two 
> additional sections:
>
> Administrator Reference: detail description of each keyword and
> parameter syntax and limitations on what they do. You might pull the
> reference information from the catalog guide and utility programs into
> major sections of this document. You've got a console and operators
> guide, but I don't see anyplace specific I'd go to get the exact gory
> details of a particular parameter.

Yes, this is a very good idea, and I will put it on the list of things to be 
done.  The problem I have is that it is a large amount of work to implement.  
The Configuration guide covers a good part of what you suggest, so possibly 
it could be broken out and expanded.

Anyway, I like the idea of having an Administrator's Reference/Guide.

>
> Administrator's Guide: which could cover discussion of the details of
> why you might want to do something a particular way. The admin reference
> covers the precise details of the commands and configuration statements,
> the admin guide discusses why you might want to do it that way and gives
> examples.
>
> More of a joke, but I'll ask anyway: have you considered a messages and
> codes manual? I know I'm being old-fashioned and mainframe-y and all
> that , but it'd be really helpful to be able to look up a message and
> know what component it related to and maybe some reasons that would
> cause that message. I don't see anywhere obvious in this structure where
> I'd look for that kind of information. It'd be a real help to the
> translators too, I'd bet.

Yes, I have considered a messages and codes manual, and in the beginning all 
the messages had unique code numbers.  Again, the problem is the work 
required to implement it, and particularly to keep it up to date as messages 
are added and changed. No doubt it would be good to have such a manual, and 
probably one day it will exist.

In any case, I am beginning to work on an entirely new manual that will serve 
as the first part of a training course as I think it is something critical 
for promoting Bacula within enterprises ...

Regards,

Kern

>
>
> -------------------------------------------------------------------------
> This SF.net email is sponsored by: Microsoft
> Defy all challenges. Microsoft(R) Visual Studio 2008.
> http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
> _______________________________________________
> Bacula-devel mailing list
> Bacula-devel@xxxxxxxxxxxxxxxxxxxxx
> https://lists.sourceforge.net/lists/listinfo/bacula-devel



-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Bacula-devel mailing list
Bacula-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.sourceforge.net/lists/listinfo/bacula-devel


This mailing list archive is a service of Copilot Consulting.