Re: [Boost-build] Boost build documentation

Subject: Re: [Boost-build] Boost build documentation
From: Edward Diener (eldiener_at_[hidden])
Date: 2013-05-13 20:30:36

On 05/13/2013 02:13 AM, Vladimir Prus wrote:
> On 08.05.2013 13:46, Paul A. Bristow wrote:
>>
>>
>>> -----Original Message-----
>>> From: Edward Diener [mailto:eldiener_at_[hidden]]
>>> Sent: Monday, May 06, 2013 8:33 PM
>>> To: boost-build_at_[hidden]
>>> Subject: Re: [Boost-build] Boost build documentation
>>>
>>> On 5/6/2013 2:44 PM, Thomas Suckow wrote:
>>>>> The Boost build documentation at
>>>>> http://www.boost.org/boost-build2/doc/html/index.html says 2006-2009.
>>>>> Has it really not been updated in 4 years ?
>>>> That webpage is indeed 4 years old.
>>>>> If it has not been updated in 4 years, could it not be updated if
>>>>> changes have been made to Boost build ?
>>>> Boost build has had numerous changes. I would use the nightly, not the
>>>> latest "stable" version.
>>>
>>> If Boost build has had numerous changes in the last 4 years I do not
>>> understand why the web pages
>> have
>>> not been updated to reflect those changes. Every link within Boost's
>>> general documentation, on the
>>> website and in the releases, which refers to Boost Build points to
>>> that web URL.
>>> What is the point of having documentation which does not reflect the
>>> current status of Boost Build
>> as
>>> the official documentation for the product on the web ?
>>>
>>>>>
>>>>> If it has been updated in the meantime could the dates be changed to
>>>>> reflect when it was last updated ?
>>>> I think the source contains newer documentation, but not much. The
>>>> information that would be really useful would be the modules that ship
>>>> with boost-build.
>>>
>>> There are lots of other things I have been told about Boost Build,
>>> usually by the kindness of
>> Steve
>>> Watanabe answering my questions, which is not in the Boost Build
>>> documentation at the URL above.
>> It is
>>> hardly just about the modules which ship with Boost build, although
>>> knowing more about them would
>>> also be helpful.
>>
>> We've accepted much kindness from Steven Watanabe and many others, but
>> collectively, we Boosters
>> have failed to get the accumulated knowledge about Boost Build into
>> our documentation.
>>
>> And the number of queries that are repeats suggests that we have
>> abused their kindness.
>>
>> Despite the noble efforts of Daniel and others, several bits of key
>> documentation, initially
>> state-of-the-art, are way out of date.
>>
>> IMO, this is because we have restricted the access to add to the
>> documentation to too few people,
>> partly through limiting write-access, but mainly from not having a
>> 'standard' Boost-way of producing
>> docs and updating them.
> 
> Do we have any write-access limits? I am not aware of any.

I agree that anyone with access to the SVN trunk can make documentation
changes to Boost build.

What I do not understand is why when some functionality changes in Boost
build, as programmed by you or other programmers who work as developers
in Boost build, the programmer who has made that change is not willing
to update the documentation. Your remark about write-access limits
implies that you expect the end-user who discovers the difference in
functionality to update the documentation. If I have a product with
documentation and I make changes to how the product works, I would make
the appropriate changes in the documentation to reflect that change
myself. I would not leave the documentation as is and then when someone
discovers the change, tell that person to update my documentation for me.

It may not be glamorous but when someone creates a product and changes
are made to the product it becomes harder for the end-user to use the
product if the documentation does not reflect how the product actually
works, so actually spending time updating the documentation is worthwhile.