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

Re: [Bacula-devel] New manual format


> > 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.

Not necessarily. There is an initial setup, and then a number of
configuration steps throughout the life cycle of the implementation.
You'll come back to the configuration information multiple times as you
make changes; the install guide will (hopefully) get used once per major
release. 

> I wanted to keep the total number of
> manuals
> to a minimum without making any one of them too large.

Personally, I'd rather have a larger manual count if the division of
what goes where is completely clear and intuitive and I don't have to
guess where something is located. The CUPS documentation is a really
good example of this strategy, as is pretty much everything IBM's ever
done. Also, since we're not printing them for distribution, we don't
have to worry about costs of printing, etc. 


> > Administrator Reference: detail description of each keyword and
> > parameter syntax and limitations on what they do. 
> [snip]
> 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.

The initial effort is pretty painful, but if you're systematic about it,
it goes quickly. It also is easier to maintain in the long run. 
 
> >
> > 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.

To be more precise, the admin guide tells you what tasks, the admin
reference tells you the precise language to use to express the task. 

> > 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.

The initial effort is the hardest. Then it's just deltas... 8-)


-------------------------------------------------------------------------
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.