forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Noels <stev...@outerthought.org>
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 xml.apache.org-centricity 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 
(http://httpd.apache.org/docs-2.0/).

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>
-- 
Steven Noels                            http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at              http://radio.weblogs.com/0103539/
stevenn at outerthought.org                stevenn at apache.org


Mime
View raw message