Re: [proposal] Forrest Wiki

[David Crossley <cr...@apache.org>]

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

Re: Improving our [proposal] Forrest Wiki

[Ross Gardler <rg...@apache.org>]

Ferdinand Soethe wrote:
> I understand Diwaker's unhappiness about our mailing lists as one
> major source of permanent information and believe that it would help
> to find an easy way of extracting important parts of on-list discussions
> into some kind of structured system.

Did you see my stuff about the mail -> Daisy app I have been working on?

Do you think this may help (no reason why it couldn't be made to work 
with MBox files to get the archives)

> However in my view this would require somebody willing to do the
> editing of such a repository on an ongoing basis or otherwise we'd
> just end up searching the wiki and then - to be sure - the mailing
> list after all.

I agree

> Yet I would be in favor of an easy to use feedback mechanism or even a
> way to add comments and tips to existing documentation since I agree
> that the hurdles for quick improvements to existing pages for
> non-committers are much to high.

Daisy (or Lenya?) can do this if that is the route we want to go - I'm 
all for gently lowering ourselves in and using other features as and 
when we identify the need.

Ross

Improving our [proposal] Forrest Wiki

[Ferdinand Soethe <fe...@apache.org>]

I understand Diwaker's unhappiness about our mailing lists as one
major source of permanent information and believe that it would help
to find an easy way of extracting important parts of on-list discussions
into some kind of structured system.

However in my view this would require somebody willing to do the
editing of such a repository on an ongoing basis or otherwise we'd
just end up searching the wiki and then - to be sure - the mailing
list after all.

I'm opposed to a documentation Wiki for much the same reasons that
David mentioned.

Yet I would be in favor of an easy to use feedback mechanism or even a
way to add comments and tips to existing documentation since I agree
that the hurdles for quick improvements to existing pages for
non-committers are much to high.

--
Ferdinand Soethe

Re: [proposal] Forrest Wiki

[David Crossley <cr...@apache.org>]

Diwaker Gupta wrote:
> David Crossley wrote:
> > 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.
> 
> I believe this is the link:
> http://thread.gmane.org/gmane.text.xml.forrest.devel/13450
> 
> I don't have any strong feelings for a Wiki. I just feel our documentation 
> needs more dynamic input. The discussion in the above thread (and its a 
> *really long* thread) was very interesting, but I wasn't able to find any 
> concrete outcome. IIUC, there was loose concensus for a CMS like system for 
> the docs where any registered user can edit content, but only Forrest 
> committers can publish content.

That is one thread that we need thanks. That one shows
that we are still talking about it, so not conclusion
That one turned into the Forrest + Lenya thread.
There were other threads too.

Actuallu the thread that i was interested in at this
stage is the one where we previously discussed a Wiki.
Ah, found it
http://thread.gmane.org/gmane.text.xml.forrest.user/98
There was not much discussion so i suppose that
everyone agreed.

David

Re: [proposal] Forrest Wiki

[Ross Gardler <rg...@apache.org>]

Diwaker Gupta wrote:
> On Saturday 30 July 2005 9:21 pm, David Crossley wrote:
> 
>>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.
> 
> 
> I believe this is the link:
> http://thread.gmane.org/gmane.text.xml.forrest.devel/13450
> 
> I don't have any strong feelings for a Wiki. I just feel our documentation 
> needs more dynamic input. The discussion in the above thread (and its a 
> *really long* thread) was very interesting, but I wasn't able to find any 
> concrete outcome. IIUC, there was loose concensus for a CMS like system for 
> the docs where any registered user can edit content, but only Forrest 
> committers can publish content.

Here's a status update on the Daisy plugin:

It now works fully, including allowing site.xml to be defined with the 
site editor in Daisy. It now communicates directly with the Daisy 
repository rather than the daisy-wiki (i.e. more efficient).

This was rolled out in a test environment late last week. Testing is 
complete in two weeks.

---

With respect to the Lenya integration (which appears to be favourite 
here for a number of important reasons):

We are still awaiting someone in the Lenya community to set up a Lenya 
instance for us. Thorsten said he would do it when he got back from 
ApacheCon but we need to be patient as he has a week of work to catch up on.

The Daisy plugin should be easily modified to allow content to be 
retrieved from Lenya instead, but without the Lenya instance we cannot 
be sure of this.

We had a number of chats with the Lenya folk at ApacheCon and I think we 
are keen to work together to find a solution. Lenya wants to use Forrest 
fairly deep inside Lenya doing much more than the current Daisy plugin 
does (which is publication only at this stage). However, we agreed that 
the first step was to create a publication plugin like the Daisy one.

---

It is important to Forrest that all documentation is also available in 
SVN for those without high bandwidth connections to efficiently edit the 
docs. The Lenya folk were telling me about a webDav block that they have 
recently implemented that also writes to SVN when a file is committed 
(or something like that).

We need to explore this with the Lenya community (which brings us back 
to the joint mailing list proposal).

Ross

Ross

Re: [proposal] Forrest Wiki

[Diwaker Gupta <di...@apache.org>]

On Saturday 30 July 2005 9:21 pm, David Crossley wrote:
> 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.

I believe this is the link:
http://thread.gmane.org/gmane.text.xml.forrest.devel/13450

I don't have any strong feelings for a Wiki. I just feel our documentation 
needs more dynamic input. The discussion in the above thread (and its a 
*really long* thread) was very interesting, but I wasn't able to find any 
concrete outcome. IIUC, there was loose concensus for a CMS like system for 
the docs where any registered user can edit content, but only Forrest 
committers can publish content.

Diwaker
-- 
Web/Blog/Gallery: http://floatingsun.net

Re: [proposal] Forrest Wiki

[Ross Gardler <rg...@apache.org>]

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