On Mon, Mar 21, 2011 at 5:22 PM, Rene Rivera <grafikrobot@gmail.com> wrote:
On 3/21/2011 3:44 PM, Stirling Westrup wrote:
On Sun, Mar 20, 2011 at 5:44 PM, Julian Gonggrijp<j.gonggrijp@gmail.com> 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