Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-08-14 16:00:53

On 8/14/17 8:29 AM, Andrzej Krzemienski via Boost wrote:

> 
> I do not even know if there is a consensus about what "look and feel" is.
> Is it only the fonts and colors, or is it also the same structure of
> documentaion in all libraries: short intro first, then tutorial, then
> reference section. If the latter, according to my knowledge, boostbook does
> not offer the ability to generate reference from source code annotations,
> so it might just put off people. You need to set up a collection of
> additional tools.

No question that addressing this is very difficult.

> This apart, some libraries have only plain HTML documentation, and some do
> not have it at all, so they would benefit immediately from being converted
> to boostbook.

Hmmm, that's not all that clear to me.  Let's use the serialization 
library as an example.  It is crafted with raw HTML.  It uses the 
boost.css so it looks similar to many of the other boost libraries. It 
was made before boostbook was available.  Writing in HTML was tedious - 
but not nearly as complicated as using the tools now popular.  And once 
it was done, it was pretty much done.  Whenever someone pointed out some 
error or it needed a small enhancement, it is is pretty simple to 
update.  It's been 15 years without much hassle.  What would be actually 
gained by conversion to boostbook?  I don't know that we generate the 
PDF anymore.  It looks pretty close the the official boostbook output. 
And has my cool documentation navigator which would be lost.

As an aside, making the original version of the documentation was an 
unbelievably contentious exercise involving acrimonious disputes between 
David Abrahams and myself mostly.  What came out of this was:

a) Concepts must be addressed explicitly in the documentation of any C++ 
library which uses templates.

b) Concept checking must be part of any C++ library code which uses 
template parameters.

c) "Concept" is a very, very, very unfortunate choice for the idea. It's 
very misleading and confusing and has led many, many people to 
understand the idea.  This believe is behind my preference for the term 
"Type Requirements" when I can get a way with this.

d) A long, contentious, strident, mailing list interaction with David 
Abrahams has to be the most unpleasant, and likely most unproductive way 
to learn anything.  I've tried to keep this mind when promoting the 
concept of "Concepts" (Damn - there's the confusion about "concept" again)>

Robert Ramey

> Regards,
> &rzej;
> 
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
>