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
