forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: [proposal] Forrest Wiki
Date Sun, 31 Jul 2005 04:21:43 GMT
Diwaker Gupta wrote:
> A lot of Apache projects have their Wiki hosted at 
> http://wiki.apache.org/general/. I think we *really* need a Wiki right now 
> for Forrest, for the following reasons:

Not so fast. We have discussed this recently in the
mail archives. The decision was not to do it because
it could be very damaging to our core documentation
which is just beginning to take shape. We agreed that
for a limited number of things we could use the
Cocoon wiki with "Forrest" prefix in page names.

We also have very recently discussed integration
with Lenya and separately with Daisy and doing our
own live server to assist with public input in a more
structured way.

However, we do need to discuss the Wiki issue as part
of the broader documentation effort. So thanks for
raising it again. Someone should find the link to
the old discussion.

More below ...

I am not trying to squash your proposal, just
merging the past discussion, and noting some
of the important things which i, for one, dislike
about the wiki solutions.

> o turn around time for making small documentation changes on the Forrest 
> website is high

Is it really? I can do a documentation review
or addition in pretty quick time and it wouldn't
be hard for any user to create a patch. This is
actually very important to encourage for some
community-building reasons. This shows them that
it is easy to contribute and encourages them to
become a devloper.

Sure wikis are fast turnaround, but that is also
a bad thing. Our current website procedure is
deliberately multi-staged and with a couple of
delays. This gives other people a chance to
review the SVN commits to see what is going to be
published and a chance to remedy that if necessary.

> o a Wiki will give chance to Forrest users to add small tips/tricks/usage data

Could also be done in our current docs.

> o some content might not make it to the Forrest website, yet might be useful 
> to someone out there. All of that can go on the Wiki

Why wouldn't it make it to the forrest website.
We don't yet have restrictions on content.

> o there's a *lot* of content flowing on the mailing lists. There are multiple 
> parallel discussions in progress, that might be difficult to track on the 
> mailing list. Most discussions are still at a preliminary stage, so we can't 
> push them out onto our website. Its hard to sort out all the threads and 
> extrac the gist on any one particular thread. A wiki would be a good place to 
> summarize/maintain the current state of discussion

Cocoon used their wiki well for that as ApacheCon
discussing the blocks and OSGi rapid development.

We could use Jira for some of this.

> o there are *so* many topics in which I think a Wiki might be more helpful to 
> grasp the big picture compared to the mailing list -- ApacheCon, 
> forrest::views, forrest::config etc (I'm *not* suggesting that we bypass the 
> mailing list, I'm only suggesting the Wiki as a *complement*)

One trouble is that it does bypass the normal
discussion mechanisms. Wikis grow out-of-hand very
quickly.

Another issue is that the Forrest PMC needs to keep
oversight on our content. Mailing lists are easy to
do that, svn diffs to our svn@a.o list okay too.
Sure wiki diffs can come to a mailing list too,
but they are very hard to follow. With still a small
PMC i wonder if we have the resources to take care of that.

> o We can use the Wiki as an incubation ground for documentation. Users and 
> devs alike can keep making incremental improvements to the documentation as 
> development proceeds. Polished documentation from the Wiki can be pushed 
> straight into the main website.

Mmmm, that is what Cocoon said at the beginning too.
They have a very successful wiki, but with heaps of repetion
that should be in the core docs. There have been very little
"polished docs" been brought back into the core, if any.

> God bless Forrest's wiki input plugin, this 
> should be a trivial task :)

It is very prone to failure though. The plugin needs improvement.

> What do people think? I could probably dig up some more reasons if these are 
> not convincing. I volunteer myself to do the initial content addition and 
> maintenance.
> 
> One little catch: I'm not sure how to go about creating one at 
> wiki.apache.org. The website has instructions, but says in bold on top that 
> they are outdated. I couldn't find any authoritative source where the correct 
> procedure is outlined. But it seems that atleast one member in the PMC 
> belonging to the group 'apsite' should be able to do it. Devs with more 
> experience on this, please advise.

It is actually a big catch. Whatever resources an ASF project
wants to use, then it should have one or more PMC members
to help with its management at infrastructure. We have not
had those resources or interest.

Anyway, if we decide to do it, then some of us would
need to join the infrastructure mailing list and find
out how to create and manage the wiki. Hopefully, they
will enhance that documentation on the way.

David


Mime
View raw message