forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: describe Forrest in 50 words
Date Wed, 20 Apr 2005 02:52:07 GMT
Ross Gardler wrote:
> David Crossley wrote:
> >A while ago we discussed our description of Forrest
> >and concluded that it was a bit limiting.
> >
> >Actually trying to concisely summarise Forrest
> >is a very difficult task.
[ snip ]
> 
> Two points, one a possible addition, the other a possible red herring.
> 
> [OT: does "red herring" make sense to the non-English speakers here, I'm 
> not sure it would work in a literal translation?, just in case it means 
> "A distractor that draws attention away from the real issue." 
> (http://csmp.ucop.edu/crlp/resources/glossary.html)]
> 
> First the possible Red Herring:
> 
> Highlighting the "internal format" concept we may be asking for trouble. 
> This appears to be the most common cause for concern for new 
> users/developers. For example, "what is it?", "wouldn't XYZ be a better 
> format?", "why do we need one?", and by far the most common "won't we 
> lose semantic clarity?".

Good catch. Yes this is intended to be a high-level
description. To address those issues we need to enhance
our own Forrest "Contract" documentation.

> I would consider simply removing the reference to the internal format 
> and focus on the transformation from one format to another.
>
> Secondly the potential addition?

The trouble is that we are already way over 50 words :-)
Never mind. Better to properly describe.

> Perhaps add something like:
> 
> "Thus Forrest can present a unified document structure and design at the 
>  output stage regardless of the chosen input formats."

Here is the proposal so far ..
------------
Apache Forrest is an XML standards-oriented documentation
framework based upon Apache Cocoon and separation of concerns.
Using a plugin architecture, various source input formats are
transformed and aggregated with other sources into various
output formats. This presents a unified document structure
and design at the output stage. Forrest can be used as a
dynamic application, or can generate sets of documents via
the command-line, and deploy with an automated robot.
------------

That is 70 words. Looking at the other project
descriptions at www.apache.org/foundation/projects.html
that puts us second behind Cocoon (77) and in front of
Struts (65).

Does anyone have more comments? We need to target the
description somewhere between the user and developer.

There is one particular comment from our email archives
that i have tried to bear in mind while altering the
description. They said that Forrest was too focussed
on web documentation and neglected other situations,
e.g. report generation. The two references to "web"
are now removed.

--David

Mime
View raw message