Re: [boost] Documentation Redux (was Re: Boost 1.36.0 release notice)

From: Dean Michael Berris (mikhailberis_at_[hidden])
Date: 2008-08-18 16:26:23

On Mon, Aug 18, 2008 at 10:49 PM, Beman Dawes <bdawes_at_[hidden]> wrote:
> Daniel James wrote:
>>
>> 2008/8/18 Dean Michael Berris <mikhailberis_at_[hidden]>:
>>>
>>> Another option (that I think Dave Abrahams has been doing) is to use
>>> RST [0] to make writing/reading the source documentation easier than
>>> having to rely on Boostbook+XSLT (which I personally think is a
>>> brittle tool-chain).
>>
>> We haven't a single problem with boostbook or xslt. It's actually
>> quite stable. The problems have been with boost build, quickbook
>> (possibly due to Spirit), doxygen and latex. Basically everything but
>> boostbook. Most of the problems seem to involve poor support for
>> windows.
>
> And even on Windows the doc build process has been mostly trouble-free. The
> only reason the doc build was such an upset 1.36.0 was that a breakage was
> detected very late in the release process. So I really don't think we should
> be talking about major changes. It should be sufficient (1) quickly fixing
> the current bug (which the docs folks are already working on), and (2)
> tweaking the process to make sure doc build failures are detected much
> earlier in a release cycle.
>

Just a thought: If building docs in windows for the release is a pain
(like most of the time I try it with the Boost.Build+Boostbook+XSLT
toolchain), shouldn't we just generate the documentation in Linux and
offer that as a separate download (or packaged with every new
release)? And would it hurt to have a documentation-only,
source/header-only, and combined package available from sourceforge?

> The "big bang" major change we need is to get CMake based building, testing,
> and reporting working well enough to use in production work. IIUC, that
> project is making lots of progress with building and testing, but hasn't
> really gotten into reporting yet. So rather than spend a lot of energy in a
> long discussion here, it would be better IMO if the Boost brainpower dusted
> off their SQL skills, and started working on report generation and query for
> the CMake based testing system. Meanwhile those of us working on release
> management will keep churning out quarterly releases!
>

The discussion I was actually looking for is more on policy (but
apparently the technology part of my post got more attention)
regarding library documentation. The technology is the easy part to
address -- we can always get better tools -- but one recurring theme
in discussions about documentation problems (in generating the docs)
is the lack of consistency/coherence/singularity with regards to not
only the look/feel of the documentation, but also with the
presentation both aesthetically (admonitions, images, indentation,
etc.) and structurally (w/ or w/o quickstart, reference documentation
format, etc.).

Right now each library has its own structure as far as documentation
goes -- and people can use whatever tools they want/need (like LaTeX
recently) to generate them. We can standardize on the tools fine, but
I guess the bigger question really is having guidelines (or templates,
if it's more appropriate) as to what each document contains, how
certain presentations have to be made (like mention the header in
which a function/class/template can be found, etc.), and what the
structure of every library documentation package should look like
(Introduction, Tutorial, Reference, Rationale, Design, etc.).

So one part of me says I agree with you Beman about getting to the
work that actually needs to be done regarding testing and reporting,
while another part of me says I'd like to be part of a solution to
make library documentation more coherent and more consistent across
the board. Part of that other conversation I'm looking forward to is
what tools we may have to standardize on to actually pull it off, but
if people feel that's a conversation that should happen later than
sooner (if ever) then that's fine by me. :)

Thanks for the attention, and I look forward to your thoughts. :)

-- 
Dean Michael C. Berris
Software Engineer, Friendster, Inc.