forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: Documentation for Forrest
Date Tue, 20 Jul 2004 09:30:22 GMT
Thorsten Scherler wrote:
> Schlierf, Stephan wrote:
> 
> >Having in mind that the existing documentation for Forrest might need some
> >improvements I'd like to agree to a proposal that was made in some postings
> >on this list - and on the dev's list, too.
> >The proposal is to use a wiki for the documentation. I agree to it because I
> >think a wiki gives people the chance to write docs in a fast and
> >straightforward way. Adding and modifying content is also quite easy.
> >Unlike this up to now the official way to contribute docs is to use the Jira
> >issue tracker (as far as I know). I consider this a little bit cumbersomely.
> 
> We want to introduce a forrest-wiki as fast as possible, but setting up 
> a wiki is quite a piece of work. Besides finishing the move to TLP and 
> the upcoming release I reckon there will be no time to set one up.

We also need to propose and discuss it on the dev list first
and then the Forrest PMC needs to request infrastructure@a.o
to set it up. No big deal, just a process. And it will probably
be me that takes the baton at the infrastructure end too.

> Like I (and others) stated before if you are keen to write down some 
> documentation in a wiki use the cocoon one for the moment. Use a prefix 
> like "forrest_" for the wiki page that will make the migration to a 
> future forrest wiki easy.

However, don't use the underscore, stick to alphabetic.
e.g. ForrestThisTopic

> The issue tracker is the best way for the project to keep track about 
> the work. That helps project management to plan for the future and keep 
> track of ressources. Besides that everything in the issue tracker will 
> (or should) not get forgotten.

Well said Thorsten.

> >What do other people think? Should we do it in the "Jira way"
> >or the "wiki way" ?

Actually, all three ways ... xdocs, an issue tracker, and a wiki.

The xdocs is our primary documentation because it travels with
the source and is so easy to add to. ANy Forrest user can do it.
Wiki would be supplementary.

> >And if a wiki, how much effort does it need to have a wiki for Forrest docs

A bit of discussion, preparation, installation, and configuration,
but not to bad really.

-- 
David Crossley


Mime
View raw message