Re: [boost] boost development process / scope

From: Jeff Garland (jeff_at_[hidden])
Date: 2007-05-04 20:43:56

Matthias Schabel wrote:

> Fortunately, there is no mandate on the specific format of  
> documentation for Boost libraries. However, I agree that it is
> desirable to have some level of consistency of documentation format.  

This is a much bigger problem than at first it appears.  I think some projects 
(like PHP and Java) get a big 'boost' from users because all the documentation 
looks the same, has the same conventions and look and feel.  Josh Bloch (on of 
the major forces in Java standard library development) credits JavaDoc as one 
of the critical elements in adoption of Java libraries.

I personally don't like the uneven look of current Boost docs.  The more 
recent docs (like math tookit, bimap, all the Niebler libs) are really nice -- 
they look pleasing and have consistent structure.  I'd like to see all the 
library docs look this way...

> I know that Steven spent a significant amount of time getting  
> quickbook to work for the Boost.Units documentation, so I would agree  
> that flakiness is a problem. Given that writing documentation is  
> generally the least favorite activity in any given software project,  
> adding even small hurdles is clearly undesirable...

The current toolchain is hard to setup, no doubt.  Overall, though, I think 
it's worth it.  Lot's of developers have managed it, so it's not that hard in 
the end. Not saying we shouldn't look at ways of making it better, we should. 
   We really need volunteers to help ;-)

The current system can clearly produce both nice html and pdf. Even though 
John and Paul struggled, they were able to get both PDF for the math toolkit 
which is chock full of references, graphs, etc.  I've had a date-time PDF docs 
for several releases.  This is a very useful feature that the straight html 
docs can't serve. The date-time docs are all in BoostBook  xml -- I really 
wish they were in QuickBook b/c it would be so much nicer to maintain them...

Jeff