On Tuesday 11 December 2007 18:39, Arno Lehmann wrote: > Hello, > > 08.12.2007 11:53,, Kern Sibbald wrote:: > > Hello, > > > > This is to let you know that over the next couple of weeks, I will be > > making a major reorganization of the manuals, and so request anyone > > wanting to make changes to the English manual to contact me first -- > > otherwise any changes you make risk being lost, which would be a pity. > > > > The changes I foresee are the following: > > > > 1. Reorganization of the manual directory structure to more easily > > accommodate multiple languages, multiple manual versions, and multiple > > manuals. > > > > 2. Divide the current 900+ page manual into a number of smaller manuals. > > I haven't yet decided exactly how many manuals to create, but at a > > minimum, I expect to have the following: > > > > Installation and Configuration > > Catalog database (installation, configuration, maintenance) > > Console (all types ...) > > FAQ > > Developers' Guide (already separate) > > Reference manual > > I mainly agree, but I think this: > > - Introduction (overview, concepts and terminology) > - Installation and Configuration > - Catalog > - Console and Operators Overview > - FAQ (we should collect them...) > - Developer's Guide > > would be even better.
Well, what I have currently separated it into is: - Catalog - Console - Developers - Installation - Problems - Reference - Utility Which is similar to what you suggest. The one part, with which I am not happy (and so I have not yet committed it) is the Reference. It really needs to be renamed and reworked to correspond to your Introduction (overview, concepts, and terminology). The problem is that it is a bit more than Introduction -- it contains virtually all the Bacula concepts. In the end, I'll probably rename it Bacula Concepts and Overview or something like that. What is missing is a sort of introduction, and I have been hesitating because at the point I start moving or adding individual sections it will have a big impact on the translations ... > > References should be included where they belong, i.e. all > configuration stuff into the "Configuration" manual, and all console > commands etc. into the "Console" manual. > > > The problem in breaking up the manual is that there is a fine balance > > between one gigantic manual as we currently have and too many little > > manuals. > > I'd approach this like this: Try to create a manual that explains > everything to a specific audience. Yes, in the end, it is going to be much better -- especially with the Problems manual, which includes the current FAQ and Tips chapters as well as other things. I can also see moving a lot of other stuff there ... > > The Introduction obviously would be necessary to everyone, from > managers deciding to have their staff try Bacula to tape operators. Yes, this is probably something new that needs to be written. It becomes quite obvious when you see the manual split the way I currently have it. > > The Install and Configuration one should have all you need to set up > Bacula, from the basic OS requirements and supported hardware to > testing and troubleshooting. Well the troubleshooting will probably be moved to the Problems manual. (It is actually named "Bacula Problem Resolution Guide". I thought of calling it the troubleshooting guide, but think Problem Resolution is a bit nicer for the translators. > > The Console manual should have everything a backup operator needs to > know (possibly separated into sections for simple tasks - like running > jobs, doing restores, etc. and advanced topics explaining the complete > commands, not requiring the menus). Yes, you are right, but this is going to take a lot of work. > > The Catalog manual should explain the setup of the catalog database in > some detail, the queries in the queries.sql file and how to adapt them > to special needs, and finally the catalog maintenance (dbcheck, > database-related tools for error recovery and maintenance (vacuum > under PostgreSQL)). > The FAQ should also be separated into several sections, applicable to > distinct audiences. > > There will probably be many cross-references... Unfortunately, cross-references are a big problem between manuals -- they do not link automatically, and that is one of the major current problems virtually all the links are broken. > > > Where > > the happy median is, I am not sure, > > I'm also not sure, but each manual should have less than, say, 200 > pages IMO. The main problem is to find a really qualified technical > writer, I believe... ;-) Well without breaking up the Concepts (currently Reference manual) we won't arrive at 200 pages. Perhaps once you see the results you will have more ideas. Thanks for the input. Kern > > Arno > > > but once the process is started and I > > have the new file structure, it should be relatively easy to split > > manuals in the future if we need to. > > > > I expect to make the same changes to the German and French manuals after > > completing the work on the English manual. Once I start that work > > (probably much later), I will send another email ... > > > > Best regards, > > > > Kern > > > > ------------------------------------------------------------------------- > > SF.Net email is sponsored by: > > Check out the new SourceForge.net Marketplace. > > It's the best place to buy or sell services for > > just about anything Open Source. > > http://sourceforge.net/services/buy/index.php > > _______________________________________________ > > Bacula-devel mailing list > > [email protected] > > https://lists.sourceforge.net/lists/listinfo/bacula-devel ------------------------------------------------------------------------- SF.Net email is sponsored by: Check out the new SourceForge.net Marketplace. It's the best place to buy or sell services for just about anything Open Source. http://sourceforge.net/services/buy/index.php _______________________________________________ Bacula-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/bacula-devel
