Re: [Boost-build] Boost.Build Documentation (on Steriods) for Newbies?

From: Dean Michael Berris (mikhailberis_at_[hidden])
Date: 2007-01-16 03:38:43

On 1/16/07, Vladimir Prus <ghost_at_[hidden]> wrote:
> On Monday 15 January 2007 14:18, Dean Michael Berris wrote:
> >
> > It might just be me, but I think it's pretty obvious that we need to
> > generate documentation that's easily accessible and easily editable by
> > the community at large. I see there's
> > http://zigzag.cs.msu.su/boost.build/wiki and
> > http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2
> > -- which one should be used, and is there an effort to actually start
> > generating (more) documentation about Boost.Build and Boost.Jam ?
>
> Just to clarify: did you saw:
>
>         http://boost.org/boost-build2/doc/html/index.html
>
> If yes, what are the problems with that?
>

I personally think it could benefit from a well-written "What is
Boost.Build" and "Why use Boost.Build" as well as a "Boost.Build by
Example" section for the uninitiated and the people with short
attention spans (like me).

I've been used to making Makefiles by hand, and would have loved to
get introduced into Boost.Build through a writeup that showed me
immediately how to use Boost.Build from the ground up. Admittedly, it
would have to include best practices, tips & tricks, techniques, and
maybe even some black magic Boost.Build hackery -- which I personally
could not write with authority.

The tutorial section doesn't give you enough to get up and start
running with Boost.Jam+Boost.Build and get clever with it for
considerably complex projects.

> > I feel there's nothing wrong with using quickbook+boostbook to
> > document Boost.Jam and Boost.Build, but downloading the Boost
> > Distribution and having to wade through how to actually build Boost
> > and the other tools causes somewhat a circular dependency problem --
> > and can be considered a serious barrier to entry.
>
> If "Boost Distibution" means Boost release, that it has all the documentation
> already generated for you.
>

Yes, and the same documentation generated is similar to that in the
on-line version (maybe even outdated, depending on the distribution
you've downloaded) which could need some help with regards to ushering
newbies into getting more familiar with Boost.Build in particular.

> > Not to mention that
> > it's pretty complex to develop documentation collaboratively in this
> > method, where it takes a considerable while between writing and
> > copy-editing and eventual release (and even the full cycle).
>
> The URL I gave updates every night.
>

How is this document generated? Is it generated from HEAD or RC_1_34_0
using quickbook+boostbook? Or using a different method?

> > Though some of us have been successful and able to figure out how
> > Boost.Build and Boost.Jam (and even quickbook+boostbook) work, some of
> > us (me included) have very short attention spans and wouldn't want to
> > go through all that again just to explain it to someone else.
>
> If you're talking about quickbook/Boost.Book setup, then it should be
> documented at
>
> http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/index.html
>
> more specifically
>
> http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/boostbook.html
>

Thanks, but what I'm saying is that we've been able to get that down
and working -- but we can't expect newbies to go ahead and dive into
setting up quickbook+boostbook just to generate and read the
documentation for Boost.Build or for any library for the matter.

We also cannot expect people who want to contribute content to the
documentation to have want to set up quickbook+boostbook just to
submit a patch to the documentation. Of course, we can choose to keep
it this way, but what I'm suggesting is that maybe we should use
something like a Wiki that allows for easy editing and proof-reading
of documentation by the community at large.

It may even allow us to "sell" the use of Boost.Build not only for
Boost related projects, but as a compelling Make replacement for
cross-platform projects.

> > So if there isn't already an effort, I would like to volunteer some of
> > my time going over what we already have and collate information and
> > have it consolidated somewhere convenient.
> >
> > Now the question is, where should I start?
>
> I suggest that you start by making a list of thing that the above docs lack,
> in your opinion. Then, document those things and send a patch to the docs.
>

I intend to do that, but which docs do I patch? The one in CVS, or the
one in RC_1_34_0?

Your response is very much appreciated.

-- 
Dean Michael C. Berris
http://cplusplus-soup.blogspot.com/
mikhailberis AT gmail DOT com
[phone]