On Wednesday 12 December 2007 21:28, Arno Lehmann wrote: > Hi, > > 12.12.2007 18:13,, Kern Sibbald wrote:: > > Oh, by the way the "Concepts and Overview Guide" is current 356 pages, > > which compares to the approx 769 pages in the current manual. So there > > is still more work to do, but I think it can well be cut down (e.g. the > > Tutorial can be moved out, ...). > > Oops... quite a chunk. > > I'm not sure if the current state of what you do is in svn... is it > possible to have a "preview" available?
Yes, it is all in the SVN now. In the next couple of days, I will figure out how to get it all up on the web site, but in the mean time, if you want to see what has happened (that would please me), I would recommend checking out a whole new copy of the svn. I haven't yet updated the README, but, assuming you have all the doc build tools loaded, you can build everything (in English only for the moment) with: cd docs ./configure --with-bacula=<location-of-source-code> make Everything will be under: docs/manuals/en/... in the subdirectories there. As I said, for the moment, I have just moved *files* around, including renaming a few. I need to coordinate this with the French and German manuals before I start moving sections ... so there is still a *lot* of work to be done. Alternatively, wait a bit more (possibly early next week) and I will figure out how to script this all to get the whole pile of documents uploaded and displayed on the web site -- it is no longer a simple affair of transferring a bacula.pdf and a directory, but it is 7 pdf files and 7 directories just for English ... Best regards, Kern > > Arno > > > 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. > >> > >> 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 ------------------------------------------------------------------------- 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://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace _______________________________________________ Bacula-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/bacula-devel
