Re: [jamboost] Re: bjam docs foor boost developers?

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-01-30 09:50:37

Hi Jeremy,

> > Actually, with V2 the priority is given on a very simple basis: if
> > user comes
> > and say he does not understand something, priority for corresponding
> > docs is
> > raisen. So, easy way to change priority is to use V2 ;-)
>
> That's great, except for the people that take one look at the docs, see
> how much is
> missing, and then walk away. That approach also ends up wasting a lot
> of users
> time. People will spend more time than necessary learning the basic
> stuff, especially
> since many will feel embarrassed to ask about the basic stuff.

:-(
It's hard to find right priorities, so user reaction is all I can use.

> But if you promise to answer every question I ask and put them in the
> docs, great!

Yes, I promise. I can't promise that every answer will make into docs 
immediately, but I'll record them all and integrate as soon as I can.

> I'll start asking away.

Go ahead. 

> > Do you refer to V1 docs, or V2 docs found at
> >
> >  http://boost.sourceforge.net/boost-build2/boost_build_v2.html
> >
> > I'd say in latter interesting information about features is hidden
> > quite deep.
>
> I was basing my comment on V1. However, a quick glance at V2 reveals
> some of
> the same problems. Who is the intended audience for that documentation?

I must admit it's a bit biased towards those trying to use Boost.Build on 
their own projects.

> It seems to be very broad, too broad. One of the first things discussed
> is creating executables
> using exe. I've never used exe. exe is for application developers.
> Boost guys
> are library developers. Our jamfiles build libraries and run tests of
> various kinds.

Library is not as good for first example, since you can't run it. Other 
examples cover libraries, too.

- Volodya