Re: [Boost-docs] [ping]questions about boost documentation

Subject: Re: [Boost-docs] [ping]questions about boost documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2007-08-22 04:41:01

Matias Capeletto wrote:
> Hi Robert,

> It is a very good idea Robert. IBD folks are working very hard in a
> lot of fronts. Please be patient, we are now more than 20 devels and
> we are starting to have real workforce. You must understand that only
> 2 months has pass from IBD first steps.
>
> Please read this section of our wiki, it was one of the first things
> we wrote: http://svn.boost.org/trac/boost/wiki/DocsOrganization
>
> Is something like this what you want?

I based my comments on the following observations:

a) the website you site
b) The directory tree in RC_1_34_1 which shows the documentation
separate from the libraries
c) The fact that the qbk generated documentation starts with
#24 or whatever suggests that the idea is to produce a comprehensive
boost document.
d) I checked out the RC_1_34_1 SVN tree and now when i navigate
to any quickbook documentation I'm forwarded to a website.  This
really got my attention and I don't like it. Later it seems that the tarball
has the html generated and doesn't exhibit this behavior. I only
recently discovered that downloading the tarball gets you something
different than doing a checkout of the SVN tree. So I'm left
with no idea of what to expect as to how this system is supposed
to work.

The website isn't clear whether the directory tree is to look like

boost_root
    doc
        library
            qbk
            docbook
            html
            pdf

Or

boost_root
    libs
        <library>
            doc
                qbk
                docbook
                html
                pdf

Its that latter that I would like to see.

>>>> The whole documentation initiative has progressed with almost no
>>>> review or testing or as far as I can see input from developers who
>>>> need/use the system.
>
> I really do not follow you here. We are not forcing nothing, just
> trying to improve things. And we have a lot of communication channels
> open, we ask feedback for almost any move.
> We are very open to discussion. I apologize no one answer you before,
> but almost each IBD devel has a lot of things to do.

I'm aware of this.

My complaint is a little different. It seems to me that the documentation
tools, quickbook, docbook, integation with bjam v2, and library
documentation are all going on in parallel.  So if I want to work
on my document, things are constantly changing so fast that
I can't keep up and get the actual document done.  What I'm suggesting
is a more formal development model for boost documentation tools.
Which would work like this:

Suppose that the last release of boost is 1.34 and library authors are
working on their next releases.  They have a boost documentation
system that can be used by authors to maintain and check their 
documentation.
This system doesn't change. Authors don't have to keep up with the
lastest / greatest markup.  It also has scripts to generate/check the
documentation renderings for one particular library.

In parallel, boost documentation tools are being improved for the
next release - Note that this new set is keep separate.  The whole
build, edit, facility is keep separate from the ones that developers
are currently using.  These new tool versions are build and run
with their own set of tests.

To summarize, authors use the latest released version which
boost tool authors separately craft the next generate of
tools, scripts, bjam files, etc.  Finally when they think they
are done, they can do a test run for their own enjoyment
on all the boost library documentation.

The boost documentation toolset, generation system etc
is submitted to the exact same criteria for release that any
boot library is.  In other words, boost . documentation
is no different than any other boost library in this regard.

 Note that I have made this same observation regarding
other boost tools/libraries. Boost/Test, bjam, etc.  In short, we should
not be using any tools/libraries while they are in development and subject
to unnoticed changes but rather we should be using tools
which have been released.   So I'm not picking on you in
particular, its just you turn.

Soooooo - I don't like the current documentation organization
if its as "monolithic" as it looks from directory tree.  And
I don't like to use tools which are currently in development.

Robert Ramey