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

Subject: [Boost-docs] [ping]questions about boost documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2007-08-20 16:50:37

I'm disappointed that no one who is actually doing this work
responded to this post.  If there is some reason that my
concerns/suggestions aren't a good idea, I would be
interested in knowing about it.  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.  The fact that a couple of
libraries have addressed these concerns in an ad-hoc
way suggests that I'm not alone in this.

Why are things being done they way are rather
than the way I've suggested.  Is there a real reason
or were no alternatives originally considered?

Robert Ramey

Robert Ramey wrote:
> In the beginning ....
>
> It was pretty simple.  Each library had a directory,
> In each library there was a directory named "docs".
> and in that subdirectory there was a bunch of linked html files.
>
> Now in the improved system - I don't know what there is.
> Sometimes I get bumped over to www.boost.org/...
>
> I find a directory in the boost_root/doc/html .. and ...
>
> When I look at a quickbook document chapter - very
> nice looking - but it starts out with chapter 24 or something.
> What's up with that?
>
> And generating local documentation for your system - like you
> need if you want to have it available if you're not near a wi-fi
> connections is a fragil process that takes a huge amount of time.
> And the recommended way to do it doesn't permit one to do it
> for just one or the other library - or test the process on just one
> library.
>
> Note that I've only spent some time looking at this.
>
> Wouldn't it be much, much easier to organize things in
> the following way?
>
> boost_root
>    libs
>        serialization
>            build...
>            src...
>            test...
>            example...
>            performance ...
>            doc
>                 html
>                      files written by hand or generated by boost book
>                 pdf
>                      files made by ? some method or by boost book
>                 boost book
>                      Jamfile.v2
>                      files made by hand or by quickbook
>                 quickbook
>                       Jamfile.v2
>                       quickbook files
>
> boost entry webpage
> boost document navigator - frame with links to all library
> documentation.
> This would permit building and maintainence of library documentation
> to be independent of that for other libraries.  It doesn't conflict
> with the way
> things were "In the beggining".  It would make it much easier
> to convert to a new, "improved" system on a library by library basis.
> It would permit users to a subset of the documentation if they
> desired. It provides a fallback if the boost documentation build is 
> improved
> beyond functionality.  It permits various distribution options - with
> and without pre-built html, pdf. or with build directories
> It would permit one to use the system to generate documentation for
> his non-boost projects.  I would be easy to convert to this system.
>
> Robert Ramey