[boost] Boost documentation

From: Gennadiy Rozental (gennadiy.rozental_at_[hidden])
Date: 2007-06-23 02:45:37

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