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. 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. The Introduction obviously would be necessary to everyone, from managers deciding to have their staff try Bacula to tape operators. 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. 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). 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... > 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... ;-) 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 > -- Arno Lehmann IT-Service Lehmann www.its-lehmann.de ------------------------------------------------------------------------- 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
