Re: [scons-devel] scons vs cmake vs bjam ...

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2003-02-28 14:17:33

"Schoenborn, Oliver" <Oliver.Schoenborn_at_[hidden]> writes:

>> -----Original Message-----
>> From: David Abrahams [mailto:dave_at_[hidden]]
>> Sent: Friday, February 28, 2003 10:25 AM
>>
>> > Main problem of the documentation is that it assumes knowledge of
>> > Jam.
>> 
>> If you take the documentation in total, which includes documentation
>> of stock Perforce Jam, there is no such assumption. Unfortunately it
>> means you have to look at a few documents before you get the big
>> picture.
>
> <rant>
> Last I looked (three months ago), the documentation for Perforce Jam was
> abominable. When the only way to find out if some basic things can be done
> is by doing searches in the mailing list archives and faq, that's pretty
> sad. I'm amazed at how many "full-fledged" utilities or libraries (in the
> sense that they have lots of functionality) are basically useless to anyone
> serious about using them because the "documentation is quite out of date but
> there's an active mailing list". Few people have the luxury of browsing
> forever through archives and posting and waiting for answers 'cause the docs
> just aren't good enough to troubleshoot without spending hours... 
> </rant>

I totally agree with you :( which is one reason I wrote
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/boost/boost/tools/build/jam_src/index.html#jam_fundamentals.
I really wish Perforce would do a more complete job of documenting
(and testing**) their code. 

>> > I don't know Jam thus there are many things I don't understand about
>> > the Boost.Build documentation. That makes it very difficult to read
>> > for someone like me, who only wants to have a quick look at how it
>> > works.
>> 
>> That's probably true; I've learned that no matter how complete your
>> reference documentation is, nobody will care unless there's an easy
>> tutorial all in one place.
>
> <mayberanttoo>
> I've found that too, and even worse, people will usually only read the
> tutorial when their progress at using the system comes to a halt, and by
> then they've forgotten about the tutorial... when they're reminded and find
> what they need, "yeah, this is a good tutorial". Just can't win...
> </mayberanttoo>

<mayberantthree>
And often people will assume the tutorial is supposed to tell them
everything they need to know and will completely ignore the reference
documentation when they get stuck, even if they remember the tutorial
will exist.
</mayberantthree>

**AFAICT Boost has the only regression tests for Jam.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com