Re: [boost] Customer Friendlier Boost Installation -- (Finally) Getting Started

From: David Abrahams (dave_at_[hidden])
Date: 2005-06-21 14:20:53

Rene Rivera <grafik.list_at_[hidden]> writes:

> Rob Stewart wrote:
>> From: Rene Rivera <grafik.list_at_[hidden]>
>> 
>>>Rob Stewart wrote:
>>>
>>>>From: David Abrahams <dave_at_[hidden]>
>>>>
>>>>>should be:
>>>>>
>>>>> It is strongly recommended that you simply <a href="...">download a
>>>>> prebuilt bjam executable</a> if we have supplied one for your
>>>>> platform.  Otherwise, you'll need to build bjam from source. You may
>>>>> also need to rebuild bjam if you are using an unreleased state of
>>>>> the Boost sources from CVS, since the prebuilt executable may not
>>>>> support all the features currently being used by Boost.
>>>>
>>>>Consider avoiding the passive "it is strongly recommended."  I
>>>>suggest this:
>>>>
>>>>   You should <a href="...">download a prebuilt bjam
>>>>   executable</a> if we have supplied one for your platform....
>>>
>>>Or similarly to something that changes the meaning less:
>>>
>>>   We strongly recommend that you simply <a href="...">download a
>>>   [etc.]
>> 
>> 
>> I don't see that mine changed the meaning.  Sure, I omitted
>> "strongly recommend," but this is a Getting Started guide, so
>> anything not equivocated should be taken as explicit
>> direction. Only the reader with enough familiarity to not require
>> the Getting Started guide will know enough to choose another
>> course.
>
> Sure :-) I was just pointing out the different, although subtle, change 
> in tone of the statement.

I don't think it's that subtle.  First of all, the reader is about to
readq some text telling them that under some circumstances they may
need to build bjam, and they are likely to think, "oh, well I'll just
rebuild it to be safe."  More importantly, we used to not say
"strongly recommend" and we ended up with lots of newbies who should
have been downloading a prebuilt trying to build their own.  I put
that language and the associated formatting in there for a practical
reason; please don't fix what ain't broke.

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