Return-Path: 
 <dev-return-13855-apmail-forrest-dev-archive=forrest.apache.org@forrest.apache.org>
Delivered-To: apmail-forrest-dev-archive@www.apache.org
Received: (qmail 33765 invoked from network); 15 Nov 2004 16:28:09 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur-2.apache.org with SMTP; 15 Nov 2004 16:28:09 -0000
Received: (qmail 50676 invoked by uid 500); 15 Nov 2004 16:28:08 -0000
Delivered-To: apmail-forrest-dev-archive@forrest.apache.org
Received: (qmail 50635 invoked by uid 500); 15 Nov 2004 16:28:08 -0000
Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:dev-help@forrest.apache.org>
list-unsubscribe: <mailto:dev-unsubscribe@forrest.apache.org>
list-post: <mailto:dev@forrest.apache.org>
Reply-To: dev@forrest.apache.org
Delivered-To: mailing list dev@forrest.apache.org
Received: (qmail 50623 invoked by uid 99); 15 Nov 2004 16:28:08 -0000
X-ASF-Spam-Status: No, hits=0.0 required=10.0
	tests=
X-Spam-Check-By: apache.org
Received-SPF: neutral (hermes.apache.org: local policy)
Received: from [212.23.3.140] (HELO pythagoras.zen.co.uk) (212.23.3.140)
  by apache.org (qpsmtpd/0.28) with ESMTP; Mon, 15 Nov 2004 08:28:08 -0800
Received: from [82.69.78.226] (helo=[192.168.0.2])
	by pythagoras.zen.co.uk with esmtp (Exim 4.30)
	id 1CTjhx-0008Fp-Jz
	for dev@forrest.apache.org; Mon, 15 Nov 2004 16:28:01 +0000
Message-ID: <4198D910.8000106@apache.org>
Date: Mon, 15 Nov 2004 16:28:00 +0000
From: Ross Gardler <rgardler@apache.org>
User-Agent: Mozilla Thunderbird 0.9 (Windows/20041103)
X-Accept-Language: en-us, en
MIME-Version: 1.0
To: dev@forrest.apache.org
Subject: User docuementation (was Re: Selective PDF - Who uses Forrest?)
References: <200411141149.20071.sean@inwords.co.za>
 <200411151230.28659.sean@inwords.co.za> <41988E9F.1000408@che-che.com>
 <200411151800.55906.sean@inwords.co.za>
In-Reply-To: <200411151800.55906.sean@inwords.co.za>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-Originating-Pythagoras-IP: [82.69.78.226]
X-Virus-Checked: Checked
X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N

Sean Wheller wrote:
> On Monday 15 November 2004 13:10, Juan Jose Pablos wrote:
> 
>>Sean Wheller wrote:
>>
>>>Current documentation assumes knowledge of cocoon. Not something an
>>>"average" user knows about. To get some understanding of how sitemap
>>>works I had to go back to cocoon. First page of documentation is only
>>>half about the average user and very quickly moves to sitemap.
>>>http://forrest.apache.org/docs/your-project.html#sitemap.xmap
>>>
>>>I leave you to draw your own conclusions.
>>
>>ok, point taken,
>>should all the Advanced customizations be out on a howto-customize-forrest?
> 

<snip/>

> 
> So far we know of two definite audiences:
> * Average user
> * Technical User
> 
> I would suggest also a developer user
> 
> Each has different information needs. Documentation needs to be built for each 
> user. Since it is not practical to maintain duplicate for each user, the 
> documentation needs to start slow, built pace and go from real simple to 
> complex. You will find at the end that you have a set of books. The 
> information architecture I would suggest is:
> 
> Description - tell them what it is, concepts and block diagram of the thing.
> Preparation - tell them what they need and how to do it.
> Installation - tell them how to install and test.
> Deployment - tell them how to deploy projects in various environments.
> Customization - tell them how to develop and customize it.
> 
> 
> Rough and very high level, but let's start with that and see other peoples 
> ideas.

One thing is for sure, our documentation is not ideal (maybe even of no 
use) for the non-technical end user. It has been said before, and will 
be said again, *any* documentation contribution will be very gratefully 
accepted. In recent weeks we have seen a number of How-To's and 
documentation patches contributed by new arrivals, this is great to see 
and I hope that this flow continues.

What we are still lacking is some core documents that bring it all 
together, your outline above looks great to me, like you said "let's start".

Ross