[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
> > two very different problems),
> Yes, I had considered doing that, but one of the goals was to try to
> each
> manual below 300 pages.  The combined Installation and configuration
> 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

> 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
> 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
> > why you might want to do something a particular way. The admin
> > covers the precise details of the commands and configuration
> > the admin guide discusses why you might want to do it that way and
> > 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
> > 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
> > know what component it related to and maybe some reasons that would
> > cause that message. I don't see anywhere obvious in this structure
> > 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
> 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
> 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.
Bacula-devel mailing list

This mailing list archive is a service of Copilot Consulting.