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-22 15:54:25

On Mon, Mar 21, 2011 at 5:22 PM, Rene Rivera <grafikrobot_at_[hidden]> wrote:
> 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.

I suppose that depends on what you are comparing it to. Compared to,
for instance, most open source software, yes the documentation is
good. But most open source software has execrable documentation, so
that doesn't put the bar very high. Compared to, for instance, most
commercial software documentation, or even just public documentation
about the STL, the Boost docs leave much to be desired.

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

I accept this. What surprised me was when I posted about the
documentation not being installed, I expected responses of the form
"Yeah, that's a known problem and we have a road map of how we'll
overcome it going forward." I didn't expect what appeared to me to be
apathy and denial about the problem.

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

Yes, and while I may think the documentation should be part of the
main package, I can understand folks who differ. If there was
somewhere I could download a PDF of the entire Boost library
documentation, or download an installable tarball of the html
documentation for the library, that would be acceptable (although not
optimal in my view). As far as I know, Boost does not offer either
option.

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

Yes. I'm wondering if one of Boost's problems is that it hasn't
managed to attract any freelance editors or technical writers to
contribute, but only programmers. If so, it would be good if some way
to address that could be found.

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

I disagree, but it may be that I am thinking of larger and more
sweeping changes than you are.

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

And I'm not trying to come across as a radical who wants to throw out
the baby with the bathwater. What I would love to see though, is the
adoption of some sort of resolution or policy decision to improve the
state of the documentation. I have to admit I'm quite fuzzy on how one
goes about making global changes for how Boost does things. In any
case, what I would love to see is a multi-step plan along the lines
of:

1) Attempt to explicitly attract technical writers and editors to be
Boost contributors, and try to ensure that their work is welcomed.
2) Create some preliminary bjam methods to relocate the Boost
documentation to standard install directories for those OSes that have
them.
3) Consider documentation that fails to work after relocation to be
buggy. I should point out that most documentation should install fine,
as it already doesn't know where the tarball is being extracted and so
should already be using relative links.
4) Move towards a set of uniform style and documentation guidelines so
that the various libraries agree on how to present information, what
needs to link to what, and what formats it should appear in.
5) Ideally it should be eventually be possible to automatically create
a PDF book of "The Boost Libraries V#.##" which one could download
and/or print out. Heck, at that point Boost could even sell dead-tree
copies of it to help cover whatever operating costs the Boost
organization might have (assuming this is compatible with Boost's
goals).

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