Re: [jamboost] Re: Tutorial edits comments

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2004-12-28 14:28:07

Vladimir Prus wrote:
> On Tuesday 28 December 2004 20:39, David Abrahams wrote:
> 
>>> +<!-- You can't launch into this stuff without describing how 
>>> to configure -->
>>> +<!-- Boost.Build... unless of course you think it's likely to 
>>> work with -->
>>> +<!-- no configuration. But even if you do you have to tell 
>>> people how to -->
>>> +<!-- configure their installation in case it doesn't work. -->
>>> +
>>> 
>>> Sure, the "how to use this document" suggest that whenever the 
>>> user decides to really try V2, he look at installation docs.
>> 
>> There are two problems:
>> 
>> 1. people typically turn directly to a tutorial and expect to be 
>> able to follow along.
>> 
>> 2. When I said "configure" I meant not just installation but the 
>> neccessary user-config/site-config settings required to find 
>> toolsets.
>> 
>> 
>>> Do you think a link is in order here, too?
>> 
>> I don't think a link is sufficient.
> 
> 
> Is complete documentation needed then? Won't that duplicate content 
> of the installation section?

Interjecting here... I can't stress enough the importance of having a
single page that takes new users from nothing through a working first
example. This is the big win the "Getting Started" page brought. First 
user questions dropped dramatically because of it. So if you end
up with duplicate docs, or having the detailed docs refer back to the
tutorial, that minor complexity is worth it for the user and us in less
time spent answering questions.

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com - 102708583/icq