Re: Selective PDF - Who uses Forrest?

[Sean Wheller <se...@inwords.co.za>]

On Monday 15 November 2004 11:35, Ferdinand Soethe wrote:
> Sean Wheller wrote:
>
> SW> My experience with the average user is that they will not use forrest.
> The SW> current system is way past the average user. If the average user
> could use SW> forrest then we would have many more example sites. The user
> that I belive SW> uses forrest is normally from a web admin or net admin
> background. Authors SW> such as myself are here because we have knowledge
> of XML and XSLT. These SW> people are not average.
>
> Agreed.

Good to see I am not alone :-)

>
> SW> Much of the documentation does not profile the average user, 90% of the
> tasks SW> explained in documentation are way beyond what the average user
> wants to get SW> involved with. The average user profile ends on the first
> page. The average SW> user wants install, copy files, and forrest run.
>
> True, but this is only version 0.7.

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.

>
> In my opinion, Forrest is one of the very few frameworks that has
> the potential to open XML-based-publishing to the normal user WHILE
> keekping the unique potential of refining a site later on by learning
> more about xslt and cocoon.

Agreed.

>
> Which is why, after spending a long time researching other products,
> I' decided to make Forrest a central topic in a book on everyday use
> of XML-technology for "normal" people.
>
> Also, it seems to me, that Forrest at the moment doesn't need a lot of
> structural changes to make it easy to use. Those that would help,
> can still be implemented until version 1.0.

Agreed.

>
> What is mostly needed is an expanded and perhaps differently
> structured tutorial explaining Forrest more from a users perspective
> plus a reference manual on all the settings and options.
>
> (I'm happy to start writing one as soon as I have a thorough
> understanding of Forrest as a whole.)*

+1 I will help.

>
> So I think the facts that you mentioned are true, but they are issues
> to improve and not arguments for changing the target audience of this
> project.

Agreed.

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

Re: User docuementation (was Re: Selective PDF - Who uses Forrest?)

[Sean Wheller <se...@inwords.co.za>]

On Monday 15 November 2004 18:28, Ross Gardler wrote:
> 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 I will knock together some outlines for people to start working with.

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

User docuementation (was Re: Selective PDF - Who uses Forrest?)

[Ross Gardler <rg...@apache.org>]

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

Re: Selective PDF - Who uses Forrest?

[Sean Wheller <se...@inwords.co.za>]

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

Re: Selective PDF - Who uses Forrest?

[Juan Jose Pablos <ch...@che-che.com>]

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?

Cheers,
cheche