forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: sync various descriptions of Forrest
Date Tue, 29 Oct 2002 12:34:14 GMT
On Tue, Oct 29, 2002 at 06:25:53PM +1100, David Crossley wrote:
> I have noticed that Forrest is described inconsistently
> in various documents. So i have gathered together the
> descriptions to start refinement. I think that we need a
> longish description (refine what we have at A) and
> also develop a one-liner.

Excellent idea.  It's the first thing users see, sent out with every
project announcement.. well worth polishing.

> The long description also needs to be more clear that
> the intent is broader than Apache.
> 
> We are going to need to make an official release of Forrest
> soon (not that i am taking on a release manager's job).
> A good clear description will be needed for that.
> 
> Perhaps we should start again and get down some dot-points,
> then develop a description from them:
> * Based on robust Apache software, practices and experience

One would hope that every Apache project has that quality.  Is Forrest
any different that it's worth mentioning?

> * Can be applied to any ASF project
> * Can be applied to your own private project
> * based on XML/XSLT
> * many modes of operation (shbat, forrestbot, webapp - but
> not using those techy terms)
> * management of local and remote website production
> * ... please add more ...
> 
> We also need to fine-tune the three main documents that
> describe Forrest (A, B, D). Forrest has progressed a lot
> and they need all review. I am happy to help out a bit.
> 
> I see that Forrest promises more than it is currently
> delivering, e.g. says that is for management of projects,
> provides statistics and metrics, makes comparison with
> Sourceforge etc. I think that this is dangerous and
> some of these should be moved to dreams.xml

+1

> Anyway here is what we have now ...
> 
> --------------------------------------------------
> A) xml-forrest/src/documentation/content/xdocs/index.xml
> B) xml-forrest/index.html
> C) xml-forrest/module.xml
> (The docs A, B, and C have basically the same intro.)
> ------
>  Forrest provides a robust technological infrastructure for
>  open software development for the Apache Software Foundation
>  based on ASF software, ASF practices and experience, and
>  modern software design principles.

Having read that, is a potential user _any_ closer to knowing what
Forrest actually is? To me it seems almost meaningless.  "robust
technical infrastructure".. an operating system perhaps? :)

How about:

  "Forrest is an XML-oriented project documentation system based on
  Apache Cocoon.  It contains XML schemas (DTDs), XSLT stylesheets,
  images and other resources used to render a project's XML source files
  into a website."

> --------------------------------------------------
> D) xml-forrest/src/documentation/content/xdocs/primer.xml
> (This is the first sentence of the "What is Forrest" section.
> It goes on to describe with more detail and some of those
> words will be useful for a top-level description.)
> ------
>  Forrest is a framework that supports the cross-project
>  generation and management of development project websites
>  using Cocoon as its XML publishing framework.

  "It not only provides access to project documentation, but also to
  other types of information that open source developers depend upon
  daily: source code repositories, mailing lists, contact info and the
  like. It aggregates all these resources and publishes them on a regular
  basis to a website"

Which isn't exactly untrue, but not very true either.


--Jeff


> --------------------------------------------------
> Other issues
> ------------
> 1) Try view-source of B) xml-forrest/index.html
> I was horrified by the HTML source there. We need to
> make it clear that this mess was not built by Forrest,
> then proceed to clean it up.
> 
> 2) Should we be referring to "ASF" or "Apache"?
> 
> 3) Do we need to mention the actual technologies (such
> as Cocoon) in a top-level description?
> 
> --David
> 

Mime
View raw message