Re: [jamboost] [BBv2 docs editorial] Installation

From: Andrey Melnikov (melnikov_at_[hidden])
Date: 2005-09-22 06:32:51

Vladimir Prus wrote:
> On Wednesday 21 September 2005 02:50, Andrey Melnikov wrote:
> 
>>Zbynek Winkler wrote:
>>
>>>Andrey Melnikov wrote:
>>>
>>>>>>Go to the
>>>>>> Boost.Build root directory and run bjam --version. You should see:
>>>>>>
>>>>>> Boost.Build V2 (Milestone N)
>>>>>> Boost.Jam xx.xx.xx
>>>>>>
>>>>>> where N is the version of Boost.Build you're using.
>>>>
>>>>IMO we can omit this step at all. Or we can add it to a more
>>>>comprehensive Installation Troubleshooting guide. We should follow the
>>>>80/20 rule - 80% of users will need only 20% of the documentation.
>>>
>>>IMO it is a necesity. I remember when I was installing bb2 for the first
>>>time, this wasn't in the documentation, so I never verified that bjam
>>>can find the bb2 files (which it could not - surprise!). I just went to
>>>an example project, run bjam and got a horribly looking back-trace,
>>>never knowing what went wrong.
>>
>>I don't understand how these paragraphs can help you. N isn't mentioned
>>any more, and it isn't clear for what do you need to run this bjam
>>--version and why do you need to know "the version you're using".
> 
> 
> Well, they do verify that bjam is installed correctly, I think. We probably 
> can give more specific instructions what to do if error is printed, but 
> otherwise this paragraph looks fine.

I see now. I think we should explicitly explain why we ask to run it. 
Also from the explanation it's unclear why we have all these numbers:

Boost.Build V2 (Milestone 10)
Boost.Jam 03.01.11

- 2
- 10
- 03.01.11

Probably we should remove "where N is the version of Boost.Build you're 
using." and put a link to the detailed explanation instead.

Or we can explain here how to describe the version presisely when asking 
people for support.

"where N is the version of Boost.Build you're using" doesn't give user 
any clue and doesn't explain anything. Now a user don't know how to use 
this information.

Andrey