Re: [Boost-docs] [poly_collection] Doc not being automatically built

Subject: Re: [Boost-docs] [poly_collection] Doc not being automatically built
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-06-08 04:10:36

On 6/7/2017 10:28 PM, Daniel James via Boost-docs wrote:
> On 7 June 2017 at 08:00, Joaquin M López Muñoz via Boost-docs
> <boost-docs_at_[hidden]> wrote:
>>
>> On a more serious note, Boost tools such as b2, Quickbook etc. and the
>> integration
>> mechanisms around documentation, regression testing, submoduling... feel
>> like an
>> arcane science without sensible references: I (and I guess many other
>> authors) resort
>> to copy and pasting from what predecessors did in the past without really
>> understanding what's going on. I wonder how much of an entry barrier this is
>> for
>> potential new Boost authors.
> 
> We all work it out as we go along, this could be documented by anyone.
> 
> FWIW I started writing some documentation on building documentation here:
> 
> http://boostorg.github.io/quickbook/doc/html/boost_doc_tools/boost_build.html
> 
> Although I don't understand the build system that well, I never
> managed to finish it, and it's out of date now as it doesn't include
> any details on how to integrate with the new setup (the boostrelease
> and boostdoc targets). It also wouldn't have answered any of your
> questions, even if I had finished it. Writing this stuff always feels
> futile, so I find it hard to be motivated enough to do it. In the end,
> it's considerably less work to just answer questions and help solve
> people's problems than write and maintain documentation that most
> never bother to read.

I disagree with your conclusion. The problem is that most people would 
not expect to find documentation about how to use Boost Build to build 
Boost documentation as part of the Quickbook documentation. Instead they 
would expect to find such informaton either as part of Boost Build 
itself or as a separate document easily accessible from the Development 
link on the Boost website under an appropriate title, such as "Building 
documentation for a Boost library".