forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sean Wheller <s...@inwords.co.za>
Subject Re: Selective PDF - Who uses Forrest?
Date Mon, 15 Nov 2004 16:00:55 GMT
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?

Personally, I am not a big fan of how-to documents. I prefer to have a 
document that is more comprehensive but starts out slow and builds as it 
progresses.

However, the audience for the book is critical. If we are talking to average 
users then we cannot assume knowledge. This approach is good for a technical 
person.

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.

-- 
Sean Wheller
Technical Author
sean@inwords.co.za
http://www.inwords.co.za

Mime
View raw message