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

Subject: Re: [boost] Missing Documentation on Building and Installing Documentation.
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2011-03-21 17:22:49

On 3/21/2011 3:44 PM, Stirling Westrup wrote:
> 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.

Given the body of library documentation I've seen, I'd have to disagree. 
The Boost documentation is overwhelmingly better than most others.

> 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.

Yes, they are reviewed as part of the library acceptance review. But as 
you must know documentation is hard to ever get right. And even harder 
to make it right and good. So we expect documentation to meet a minimal 
set of usability requirements. But like all things programming, we don't 
expect perfection. There will always be bugs in code and documentation.

>> 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?

It means, that if you want to read the documentation locally you untar 
the package locally and keep it around.

> Does installing the header files ==
> extracting the Boost distribution tree?

For some people it does. But less so on Unix variants, than say Windows. 
Some people, like myself who wrote the initial install scripts, never 
actually use the install procedure. I.e. I just use the sources directly 
and likely never build the usual set of installed libraries. Opting to 
"embed" the libraries within the project that happens to be using them.

> Does installing built
> libraries in all their various (threading/non-threading,
> shared/static) forms == extracting the Boost distribution tree"?

No. But sometimes building them, and using them *without* installing 
them is done. People are fond of building and checking them into their 
VCS system for their team to use directly.

> 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.

It's also common for packages with large amounts of documentation to 
never install documentation locally. Instead opting to provide separate 
platform independent downloads. Many times in form of PDF or HTML books.

>> 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.

Of course.. But if others don't point out the documentation bugs how can 
one expect them to get fixed promptly. You must be familiar with the 
problem of authors correcting their own writing. And hence why there are 
book editors, reviewers, and errata.

>> 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.

Very unlikely.

Note, I'm not discouraging improving the handling of documentation. Just 
trying to put some pragmatic reality into the picture ;-) And having a 
way to "install" documentation might be good. But given the varied 
documentation content it's not as easy as one might think.

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org (msn) - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim,yahoo,skype,efnet,gmail