forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Noels <>
Subject Re: Forrest is overdocumented
Date Tue, 12 Nov 2002 15:06:19 GMT
Jeff Turner wrote:

> Users are practically swimming in documentation, unfortunately mostly
> slightly out of date.  I foolishly tried to update the Forrest Primer,
> and found that outdated is absolutely
> everywhere.  Rewriting an existing doc is actually more effort than
> writing one from scratch, because added content has to 'fit', not
> duplicating anything.  The change 'infects' the doc around it, requiring
> a cascade of updates.  primer.xml is a nightmare because it touches
> everything.

Yeah. That was the idea, basically, since there was no real 
documentation at that time. The same will hold true for your-project.xml 
in a month or two, too. We need to componentize our documentation in a 
set of interrelated, but independently managed snippets, that have the 
same level of updateability as status.xml.

> IMO the site needs a ground-up rewrite, containing the absolute minimum
> of content.  We could have a separate tab, 'legacy', containing the
> current site.
> </rant>

No, <truth/>

Now, let's fill this empty element :-D

> :)
> Though I must say, the quality of Forrest's docs (before the code changed
> under it) says a lot about the dedication of Forrest's committers.  The
> site authors all deserve some serious toothbrush awards.

Since we all claim to be docowizards, let's try to achieve the same 
level of granularity the httpd docs have 

So what are the main components of Forrest?

  * featurewise / use-case driven

    - installation & configuration
    - seeding & first steps
    - dtd user documentation
    - 'cron'-ing forrest
    - ...

  * technically

    - grammars & CAP
    - uri namespace
    - pipelines
    - skins
    - forrestbot
    - ...

Later on, we can add 'trails' that lead people to the correct info.

Steven Noels                  
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at    
stevenn at                stevenn at

View raw message