forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject User docuementation (was Re: Selective PDF - Who uses Forrest?)
Date Mon, 15 Nov 2004 16:28:00 GMT
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

Mime
View raw message