Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-08-14 15:15:37

On 8/14/2017 10:37 AM, Robert Ramey via Boost wrote:
> On 8/14/17 12:40 AM, Andrzej Krzemienski via Boost wrote:
> 
>> I do not know anything about the project, so I am not really addressing
>> your question,but I wonder how it is possible to get a unified look and
>> feel across all the libraries when library authors are given freedom 
>> to use
>> whatever format for their documentation, whatever tool, and whatever
>> approach to documentation.
> 
> I don't think it is possible.
> 
> This leaves us with a couple of options:
> 
> a) Enforce the usage of boost book for documentation as condition of 
> acceptance and inclusion of a library in boost. This would guarantee 
> consistent look and feel across libraries.
> 
> b) Encourage everyone to "do their own thing".  Which would almost 
> certainly result in a wide variation of look and field.
> 
> c) Improve the boostbook documentation and related tooling to make it so 
> compelling that only an idiot or egomaniac would decide not to use it. 
> This would be the best of course.  But it's a lot of work and we're not 
> there yet.  And of course in any large organization, there's always a 
> couple of idiots/ecomaniacs or people who act that way on an occasional 
> basis.
> 
> Actually, this was the motivation for my post.  I think when this 
> initiative was announced we were on the right track.  But I think we 
> lost our way on this one.  I don't know if it's possible to all get back 
> on the same page, but it would be a good thing if we could.

The main objection to the quickbook - boostbook - doxygen way of 
generating documentation, as I understand it, is that it is very hard to 
generate a different look-and-feel to the documentation from the 
standard one created by the stylesheets. OTOH others think having the 
same look-and-feel of all Boost docs is an advantage. So I do not think 
there is any way around this basic disagreement.

I do understand that other issues have been mentioned, such as lack of 
support for diagrams ( graphviz ? ) or formulas ( MathML ? ) directly in 
quickbook. But we have the source for quickbook and can modify it 
accordingly, so I do not think that quickbook is itself the problem. I 
do agree that writing directly in boostbook ( or docbook ) is a real 
pain, which I have always found I could forgo, but quickbook has always 
been supremely easy to use for me.

> 
> Robert Ramey