[Bacula-devel] Fwd: Re: Bacula documentation

[Kern S. <ke...@si...>]

Hello,

As you can see from the exchange below, Andrew Ford has volunteered to help 
edit the Bacula manual(s).  This is really good news for me because he brings 
a good amount of experience to this important piece of Bacula as well as a 
fresh eye, which will surely help improve the comprehensibility of the manual 
for new Bacula users.

Best regards, Kern

----------  Forwarded Message  ----------

Subject: Re: Bacula documentation
Date: Saturday 27 August 2005 10:45
From: Kern Sibbald <ke...@si...>
To: Andrew Ford <A....@fo...>

Hello Andrew,

I have long dreamed of having someone competent in English who would like to
help organize and cleanup the documentation.

On Friday 26 August 2005 11:41, Andrew Ford wrote:
> Hi Kern
>
> I submitted the bug report about the structuring of the Bacula
> documentation and got your reply (sent from the bacula-bugs list).  I
> replied to your comments but the list is moderated -- I don't know
> whether you got my reply.  I am writing to you off-list as I would
> prefer to get your feedback before talking publicly about this.

No, I didn't get your reply. The list is read-only, the way to add
 information is to add a "bug note" to the bug report using the database
 interface.  This means of contacting me is fine.  I have no problem if it is
 on-list, in fact, I prefer it that way.

> I am very interested in working on improving the documentation of Bacula
> -- it is a good way to get to really understand the program and also to
> help others to understand it better.  I have written a number of books
> (Spinning the Web (ITP, 1994) and the Apache and Mod_perl pocket
> references (O'Reilly)) and have edited and published a couple of
> non-computer books, using LaTeX for production.  I have used LaTeX for
> more than 15 years now.

Nice. Just what the Bacula project needs.

> I think that the manual would benefit from a light editorial touch.

Yes, I agree.

> There are places that it is unclear, for example the manual talks about
> Client and FileDaemon resources but doesn't explicitly say that they are
> aliases, it mentions UA but does not explain what that is (although
> perusing the source code it becomes clear).  Most potential users of
> Bacula are going to make an initial judgement about the program on the
> basis of the documentation.  Stepping back a bit I think that some of
> the material could be reorganized, although I would need to understand
> Bacula more than I do now before I could attempt this.

I've tried to define terms before I use them, but when one knows the subject,
it isn't always easy and as you point out, it creates confusion and a bad
image. I'd be pleased to have this fixed.

> The typesetting could also be tightened up somewhat -- with due
> consideration given to both the PDF and the HTML output.  Examples here
> would be to have running headers in the PDF that reflect the current
> chapter; enlarging the text area on the page somewhat, which would
> result in a lower pagecount (to save on paper and make the manual less
> unwieldy).  There are other things such as spurious spaces in index
> entries and the formatting of tables that could be improved to give the
> manual a more professional appearance.

Yes, there are a *lot* of things that could be cleaned up.  We just went
through a conversion from html to tex in this release and though the output
is reasonable, it is far from optimal.  Karl Cunningham <ka...@ec...>
has been an invaluable help in doing the conversion with his knowledge of
Perl, he has adapted our text for the most part with Perl scripts.

I'd still like the online web manual to look more like the Python manual,
which is much more professional looking.

> Apropos of the sectioning: I have made a copy of the documentation
> directory from CVS and have been playing with the files.  I changed from
> the starred sectioning commands to the unstarred and got LaTeX errors in
> the user manual but not the developer's manual.  I then commented out
> all the \include directives in the user manual except the first and the
> document formatted fine.    I then started uncommenting them one by one
> and so far the problems have not recurred, so I think that the problem
> is probably just in one or two included files and can be isolated and
> fixed.

If you could fix this, it would be great as I agree with you, for the pdf
manual, it is really not very convenient without the section numbering.

> I really do think that the manual should have proper numbered chapters
> and sections.  If this causes problems in the LaTeX2HTML process then
> those could be addressed -- LaTeX2HTML is, after all, infinitely
> flexible.  Having proper chapters would mean promoting "\section"s to
> "\chapter"s and so on.
>
> Would you be interested in me taking on the job of editing the Bacula
> manual?

Yes, very much so.

The only condition I would make, which may be a bit hard for you, is to keep
the manual in American English (I think parts of the SD chapter are in
British English).  The reasons for this are:
1. My English is American English
2. American English is much simpler and closer to how we actually pronounce
words.  For example: color is pronounced col - or  not  col - our; program is
pronounced pro-gram  not pro-gram-me.
3. I believe (may be wrong) that American English is used by more native
English speakers than British English, though due to British colonies,
British English *may* be more widely used.

Anyway, I don't want to get into an arguments over English, but just point
this out as something to keep in mind so that the manual remains consistent.

> If you are interested in input on the documentation should this
> be discussed on the devel list?

Yes, this information should be on the devel list.  However, often there are
little questions that would not really interest everyone, and in those cases
it is OK to correspond offlist.

One of the biggest pieces of work that needs examining is the index.  It is
something new in this release, and it was 99% generated by Karl's scripts, so
it could use a bit of tweaking.  I just have not had time to look at it.

One of my projects that would interest you is to split the manual into the
following different manuals:

1. Bacula manual (intro, general -- sort of a how-to and examples, more
    or less what a book on Bacula would be).
2. Bacula reference (details of all directives)
3. Installation manual
4. Rescue (installation and how-to)
5. Bacula GUI (bimagmgr, bacula-web, wx-console, ...)
6. Bacula tutorial (current tutorial chapter with a bit more).

If you still would like to work on this, I think it would be useful to you to
have read/write permission on the developer's CVS.  To do that I need your
login name on Source Forge.  If you don't have one, you simply sign up for
one at Source Forge.

If you have no objections, I would like to send this email to the devel list.

Thanks for your interest in this project. :-)

--
Best regards,

Kern

  (">
  /\
  V_V