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

Subject: Re: [Boost-docs] [ping]questions about boost documentation
From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-08-22 05:35:47

On 8/22/07, Robert Ramey <ramey_at_[hidden]> wrote:
> 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.

IBD has nothing to do yet with the release process. We are working on
a separate SVN tree placed in the sandbox.

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

Me too.

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

This is exactly what we are trying to accomplished.

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

Agree.

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

This is what we are doing now :)
I really think you should read the complete IBD Wiki. We may have to
add more devel info there, if you have already read it. Please give us
feedback in this front.

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

Yep.

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

Robert, please work with us! We share a lot of ideas :)

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

In this front, some of us are proposing to start a Quickbook community
independent of Boost (but very close to it). We are moving in the
direction you want.

> So I'm not picking on you in particular, its just you turn.

I do not feel any picking from you, do not worry.

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

:)
Me neither! And a lot of other boosters too. IBD was created because of that.

King regards
Matias