forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: Creating documentation (Re: Link to CSS howto-structurer-dsl.html)
Date Sun, 18 Dec 2005 13:59:58 GMT
Calmbach, Richard wrote:
>>-----Original Message-----
>>From: Ross Gardler [mailto:rgardler@apache.org] 
>>
>>(this is a general comment not at all aimed at the authors of 
>>these mails - since I'm in that group)
>>
>>Why is it that people take the time to write clear 
>>documentation like this but nobody puts it into a document?
> 
> 
> I noticed that Forrest doesn't have a wiki at http://wiki.apache.org/,
> unlike many other Apache projects. A wiki may facilitate the creation of
> documentation for new features that are still under development. There
> is close to zero overhead in adding and revising content. The additional
> benefit is that users who want to experiment with the latest code have a
> central place to go for information. It's sometimes difficult to find
> specific info in the mailing list archives. Once new features have
> stabilized, the wiki pages can be converted to xdoc and moved to the
> official documentation.
> 
> WDYT?
> 

We've discussed this in the past. There are problems with wiki's - they 
become very unstructured and confused very quickly. Without careful 
management they start to contain incorrect and outdated materials.

Forrest is moving quickly since we are not yet at a 1.0 release, 
consequently the docs move very quickly (or at least should ;-)

Since we are a small dev community at present we are not sure we could 
keep a wiki in order. For more discussion on this see our dev archives.

HOWEVER
-------

We have also discussed having a CMS for our official documentation. 
There are some problems with this (in particular that users are forced 
to use a web interface rather than their chosen editor and SVN).

We agreed to use a Lenya instance and build a plugin to publish the 
content as a static resource.

Thorsten did put together an instance of Lenya on their Zone. However, 
there were some stabaility problems with it and the set-up never got 
finished for our use.

In the meantime Cocoon has been using Daisy as its Documentation system. 
  The plugin for publication has been built and their latest release 
included docs generated from the CMS. The experiment has been a great 
success, improving the level of documentation contributions and 
improving the organisation of the docs.

PROPOSAL
--------

I am supporting the Daisy plugin. My offer to assist with the 
development of a Lenya plugin remains in place (this comes up 
periodically on the Lenya lists, I always repeat my offer but to date 
none of the Lenya devs have been motivated enough to step up to the plate).

Lets get it done, lets get a CMS instance in place. My position remains 
the same as before, if we use Daisy I will support it directly in terms 
of the plugin and the installation and configuration of Daisy (although 
we could ask to share the Cocoon install since they have the direct 
support of Bruno, the "cheif" Daisy dev and I am alreay an admin on there)

If people would still prefer to use Lenya, I have no objection, other 
than it actually has to happen. It has to be installed, made stable, 
configured for our docs and the plugin built. I will help with the 
plugin where I can (since the Daisy plugin is quite functional now it 
shouldn't be hard to build the plugin).

So, are we going to do this or are we just going to talk about it every 
six months ;-)

Ross

Mime
View raw message