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

From: Jeremy Siek (jsiek_at_[hidden])
Date: 2004-01-30 09:03:14

Hi Vladimir,

On Jan 30, 2004, at 3:00 AM, Vladimir Prus wrote:
> Hi Jeremy,
>
> > The main point I'd like to make is that when it comes to bjam docs,
> > it would be nice if priority would be given to documenting those
> > features that are used the most by the end user (in this case,
> > the boost developer, not a bjam developer).
>
> Actually, with V2 the priority is given on a very simple basis: if=20
> user comes
> and say he does not understand something, priority for corresponding=20
> 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=20
how much is
missing, and then walk away. That approach also ends up wasting a lot=20
of users
time. People will spend more time than necessary learning the basic=20
stuff, especially
since many will feel embarrassed to ask about the basic stuff.

But if you promise to answer every question I ask and put them in the=20
docs, great!
I'll start asking away.

> Do you refer to V1 docs, or V2 docs found at
>
> =A0http://boost.sourceforge.net/boost-build2/boost_build_v2.html
>
> I'd say in latter interesting information about features is hidden=20
> quite deep.

I was basing my comment on V1. However, a quick glance at V2 reveals=20
some of
the same problems. Who is the intended audience for that documentation?
It seems to be very broad, too broad. One of the first things discussed=20
is creating executables
using exe. I've never used exe. exe is for application developers.=20
Boost guys
are library developers. Our jamfiles build libraries and run tests of=20
various kinds.

Cheers,
Jeremy

_______________________________________________
Jeremy Siek <jsiek_at_[hidden]>
http://www.osl.iu.edu.edu/~jsiek
Ph.D. Student, Indiana University Bloomington
C++ Booster (http://www.boost.org)
Office phone: [phone]
_______________________________________________
 --Apple-Mail-1-527430203 Content-Transfer-Encoding: quoted-printable
Content-Type: text/enriched;
charset=ISO-8859-1

Hi Vladimir,

On Jan 30, 2004, at 3:00 AM, Vladimir Prus wrote:

<excerpt><fixed>Hi Jeremy,</fixed>

<fixed>> The main point I'd like to make is that when it comes to bjam
docs,</fixed>

<fixed>> it would be nice if priority would be given to documenting
those</fixed>

<fixed>> features that are used the most by the end user (in this =
case,</fixed>

<fixed>> the boost developer, not a bjam developer).</fixed>

<fixed>Actually, with V2 the priority is given on a very simple basis:
if user comes </fixed>

<fixed>and say he does not understand something, priority for
corresponding docs is </fixed>

<fixed>raisen. So, easy way to change priority is to use V2 ;-)</fixed>

</excerpt>

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.

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

I'll start asking away.=20

<excerpt><fixed>Do you refer to V1 docs, or V2 docs found at </fixed>

=
<fixed>=A0<color><param>0000,0000,EEEE</param>http://boost.sourceforge.net=
/boost-build2/boost_build_v2.html</color></fixed>

<fixed>I'd say in latter interesting information about features is
hidden quite deep.</fixed>

</excerpt>

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?

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.

Cheers,

Jeremy

_______________________________________________

Jeremy Siek <<jsiek_at_[hidden]>

http://www.osl.iu.edu.edu/~jsiek

Ph.D. Student, Indiana University Bloomington

C++ Booster (http://www.boost.org)

Office phone: [phone]

_______________________________________________

 --Apple-Mail-1-527430203--