Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-08-16 15:03:38

On 8/16/17 1:25 AM, Gavin Lambert via Boost wrote:
> On 16/08/2017 17:39, Robert Ramey wrote:
>> regardless of the details, just the look of the diagram is pretty 
>> intimidating.  On the the other hand, once you the tools, scripts, etc 
>> installed, it's just a matter of calling boost build so everything is 
>> hidden.  This makes it pretty simple ... until it doesn't which is 
>> just about always.
>>
>> I actually like the whole system and I think it's pretty well suited 
>> to boost.  BUT, the combination with boost build and the desire to 
>> hide all the complexity makes it more difficult to use rather than 
>> easier.  I think if we could work on this, we might persuade 
>> developers to stick with it rather than looking for alternatives.
> 
> So it needs better meta-documentation? :)

LOL - very clever.  But I actually look at the problem in a different 
way.  It's my view that when something is hard to describe/document it's 
a symptom that there is design error somewhere.  So that it's time to 
step back and see what mistake you made which leads to something too 
complex to understand.  With the boost documentation system there are 
couple of suspects:

a) The embedding of the complex tool chain into bjam. Of course this is 
technically doable and results in a very slick - "do what I mean 
interface" (DWIM tm robert ramey).  But with something this complex no 
one can anticipate all the exceptional cases and when they occur, the 
system leaves one bereft.

b) The inclusion of all the specialized tags for C++ like class, struct, 
is meant to automate the production of boiler plate output for those C++ 
constructs.  I understand the appeal of this - we're computer 
programmers and want to automate everything - but in this case it's a 
bridge too far.  quickbook doesn't use these - a good choice in my 
opinion.  A few hand edited boost book do uses these but the results are 
not satisfying in my opinion.  To improve them, one would have to wade 
into XSL language - a place were few people want to go.

In short, better documentation of the toolset wouldn't hurt, but I don't 
think it would solve the whole problem.

Robert Ramey

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