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 [EMAIL PROTECTED] 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
