forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [proposal] Forrest Wiki
Date Sun, 31 Jul 2005 13:50:58 GMT
David Crossley wrote:
> Diwaker Gupta wrote:

...

>>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.

I'm of a differnet opinion here. If a user is reading the docs and wants 
to make a clarification it is difficult for them to do so, even if they 
know the structure of our project and they know how to do a patch.

At the very least they have to open an editor, find the right source 
page (remember they were probably reading from the web site), find the 
right part of the page, edit is, create the patch, log in to jira, type 
a description of the issue, upload the patch.

A pretty long process. Now consider a user may not have the src on their 
disc (binary download), may not know where the files are stored, may not 
know how to make a patch, may not have SVN installed etc. etc.

It is my opinion that to encourage users to contribute we need to make 
it as easy as possible. Once they start doing things like XSL tweaks we 
can show them how to do patches.

> 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.

I agree. But see my proposal in the Daisy/Lenya thread. It covers all 
these aspects, providing exactly the same mult-staged approach (or an 
improved one if we can find it).

>>o a Wiki will give chance to Forrest users to add small tips/tricks/usage data
> 
> 
> Could also be done in our current docs.

Not easily, see above.

>>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.

Perhaps in development docs, unreviewed docs, etc. Right now we have 
nowhere to put these types of docs, they either sit in the mail archives 
  (where we forget them) or they go into the site too early.

>>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.

Here's another good example of the type of doc that may not make it into 
the final published site, but is useful for us to keep. The proposal I 
made for Daisy/Lenya + Forrest accomodates this kind of usage.

> We could use Jira for some of this.

Possibly, I'd like to hear a proposal for this. I agree we do not use 
Jira well at present.

>>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.

With respect to bypassing normal discussion:

I have (almost) completed an app that mirrors a mail list in Daisy 
(could easily be Lenya). The idea is that discussion continues on the 
mail list as normal, but when a consensus is reached you can drop into 
the CMS and you already have the content of the mails. This then enables 
you to edit the content accordingly, remove superflous comment, clarify 
valuable comment etc.

With respect to "growing out of hand":

The two stage publishing process I originally proposed allows the "free 
form" editing of content (which is a strength of a wiki style system) 
but also allows that content to be organised in a logical way for 
publication to the site. That is, the structure of the CMS need not be 
the same as the published site (or even sites).

> 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.

Agreed. This is why I am particularly interested in the fact that Lenya 
plan to have a repository interface to SVN. People could then use the 
tools they prefer for their particular task. That is users can use a 
simple web based interface, PMC oversight is via SVN commit messages, 
developers use their preffered editors and svn client.

>>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.

Yes, what is lacking in Cocoon is organisation. My proposal allows us to 
maintain the organisation in the published docs but allow the organic 
growth of the "wiki" content.

But it takes work to manage that - do we have the resources?

>>God bless Forrest's wiki input plugin, this 
>>should be a trivial task :)
> 
> 
> It is very prone to failure though. The plugin needs improvement.

The wiki plugin is dead (sleeping?), long live the daisy plugin (and 
Lenya plugin)

I would be -1 on the wiki, but +1 on Lenya, Thorsten, can we have the 
Lenya instance in the Lenya zone for this?

Ross

Mime
View raw message