Re: [boost] Missing Documentation on Building and Installing Documentation.

Subject: Re: [boost] Missing Documentation on Building and Installing Documentation.
From: Stirling Westrup (swestrup_at_[hidden])
Date: 2011-03-21 16:44:50

On Sun, Mar 20, 2011 at 5:44 PM, Julian Gonggrijp <j.gonggrijp_at_[hidden]> wrote:
>
> You are confusing two issues that are completely orthogonal to each
> other.

The point I was trying to make is that documentation seems to be a
neglected side of the boost project, BOTH in quality and structure.
There are formal reviews of new libraries. Is the documentation
subject to the same reviews? If so, I can only say the reviewers have
been falling down on the job.

>
> 1) The way the Boost documentation is structured.
>
> It's simple: the C++ code is part of the documentation. Hence,
> installing the documentation == extracting the Boost distribution
> tree. There is nothing wrong with this approach; it reduces
> "documentation duplication" which, exactly like reducing code
> duplication, is a good thing.

What exactly does "installing the documenation == extracting the Boost
distribution tree" mean? Does installing the header files ==
extracting the Boost distribution tree? Does installing built
libraries in all their various (threading/non-threading,
shared/static) forms == extracting the Boost distribution tree"?

If I download a tar ball, extract and build according to the rules
given, install everything and then delete the tarball and its
associated temporary files, I have my headers, I have my libraries,
but I DO NOT have any documentation. Since this is the standard way of
installing things on Linux and since the installation documentation
gives nothing to dissuade someone from this methodology, it appears
(to me) to be a major problem.

>
> 2) The quality of the part of the documentation that is not C++ code.
>
> Of course there may be errors in the documentation. In that case
> you're free to file a bug, just like with the C++ code.

Oh sure, but I've come across programming bugs in Boost once or twice,
ever. I come across documentation bugs on the order of 3 or 4 times
every day. If someone were to judge the quality of Boost based on its
documentation quality, they would get a very incorrect view.

> To conclude, changing the approach in 1) would not solve the issues in 2).

Changing the Boost procedures stop treating documentation as an
afterthought would fix both problems.

-- 
Stirling Westrup
Programmer, Entrepreneur.
https://www.linkedin.com/e/fpf/77228
http://www.linkedin.com/in/swestrup
http://technaut.livejournal.com
http://sourceforge.net/users/stirlingwestrup