Hi, I've been offline for a bit. But I was able to spend several weeks learning DocBook. I must say I was really impressed with quality of this project. I also tried to get a grasp of BoostBook and gave perfunctory look on quickbook. Here I would like to share my thoughts on recent "doc update" movement. I. quickbook as documentation media. Why, oh, why don't we learn from our own mistakes. We just started to realize the problem we got ourselves into with makesystem. And immediately find new toy to play with. However fun it is, however cool it might look on first sight, THIS IS NOT OUR BUSENESS to invent/support documentation format. DocBook is very mature, well supported project. It's based on widely accepted/supported technologies. It's powerful and configurable to implement essentially anything one need. I personally don't see much valid reasons to look in home grown format direction. Here some specific points: 1. Simplicity Some people argues that it's easier to type quickbook I might argue that it's actually opposite. Granted if you use vi XML editing is not fun. But myriads of modern XML editors simplify the process marginally. There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. In addition you get immediate format validation and presentation (using assigned stylesheets) 2. Any change in DocBook have to be reflected in quickbook terms 3. Someone need to maintain quickbook parser/transformer 4. quickbook will never be as flexible as DocBook 5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters. 6. Source code highlighting My understanding is that quickbook presents some source code highlighting automation. IMO this can be either implemented as standalone C++ based tool that docs writers can use when required or even better it can be implemented in JavaScript. I believe I've seen it done. All in all I believe using this format is going to be a maintenance problem in a long term and should be avoided. We should stick with industry standard DocBook IMO instead. II. BoostBook 1. Complexity The BoostBook being an extension to DocBook seems to be doing too much. IMO any useful generic innovations should be proposed to the DocBook developers and eventually removed. All in all we should strive to make this layer as thin as possible. 2. Test suites support. I did not really grasp the idea behind this feature completely, but from what I understand this is "misfeature" and should be removed 3. Tight coupling with Boost.Build This is major problem I believe. Especially in documentation. BoostBook should be presented as independent project. It should be explained how to use it, configure it without any reference to Boost.Build at all. At the very last chapter of documentation we may refer that if you want you docs to be automatically generated on some remote host (if let's say you don't have all the tools set up locally for all the formats) this is what you need to do ..... 4. Documentation I found documentation to be largely unacceptable (funny thing for the project dedicated to writing documentation) a) No explanation how to use BoostBook without Boost.Build (see above) b) all he elements description are without examples c) most critical: no description whatsoever of all the modification done in comparison with DocBook. All the updated parameter need to be listed, all the updated templates need to be explained. General approach should be what the person familiar with DocBook (standard) need to know/expect to use BoostBook d) No explanation on how to extend the BoostBook (especially in comparison with DocBook) As I mentioned before we should try to limit our extensions to the most necessary only and strive to stick with standard DocBook. Also all extensions should be made optional. III. What should we do? IMO the standardization efforts need to target DocBook/BoostBook. On the other hand each developer should be allowed to extend/twick standard L&F. Usually differences should be only cosmetic. Following are general observations about common L&F 1. JS Menu support. I believe it should be implemented but made optional. I personally don't like it (I believe it's just wait of space for this menu to stay on all the time) and prefer "location path" kinda navigation Boost.Test currently using. 2. Header on top. I don't believe it's necessary. Neither in a form of boost|libraries|more|... nor what is currently proposed. This information is accessible from boost main page. No need to duplicate it on every page of every library. 3. Frames I personally need frames support for the reference like pages (like in preprocessor and test libraries). I am open to the alternative that presents similar L&F. 4. Portability This is major requirement for all the features we implement. They should work on at least set of predefined "major" browsers. Please make this as discouraging comments to overall documentation efforts movements. I just don't believe we move in right direction. Regards, Gennadiy