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