Mark Leicester wrote:
Hi Bertrand,
I for one have been looking at the wiki regularly, making little tweaks here and there: nothing major, but it's a regular haunt of mine. You can verify this at: http://wiki.apache.org/cocoon/RecentChanges (S�bastien seems to have contributed a fair bit recently too!)
Back when Outerthought introduced the Cocoon wiki I thought it was a cool tool (hey, not even based on Cocoon!). I liked it and introduced it into my company too: we used it lots. We learned the good and bad of wikis. Later, in my constant search for community enhancing tools, I came across Drupal (a tool that is proving very successful all over the problem space). I'm inventing as little as possible. That is, I'm building on the work of others, at the same time as trying a slightly different approach to that proposed already.
I think that when you suggested, "This is maybe the one tool that we're missing: a way to add folksonomy tags to our docs to make them easier to find", you are touching upon an important weakness of the wiki. The wiki is great for contained ideas and snippets, but very poor at encouraging the organisation of those snippets. With a wiki it is difficult to evolve a taxonomy from the content (yes, there are ways). Bertrand, I know you are a fellow user of del.icio.us and from that, and your statement above, I think we may essentially agree on the potential solution. A "jewel" in Drupal's "crown" is its taxonomy system. Over the next few weeks I'll attempt to demonstrate the benefits of this approach, coupled with folksonomy. Taxonomy is 'expert' pre-defined, folksonomy is community post-defined. I think the latter has enormous potential to help in a community like ours. A bit of both is probably perfect.
I think you are right, I probably have dismissed the "existing stuff" a bit early. In that case, I pledge to keep in touch with the current effort. I certainly value ongoing dialogue. However, I wonder out loud: should we be putting documentation behind the barrier of committership at all? I'm a community post-defined kind of person.
As I said above, over the next few weeks I'll attempt to demonstrate what I imagine to be the myriad of potential benefits of the Drupal approach.
Please go on in this folksonomy approach. It definitely looks interesting.
Documentation of any large system is twofold:
- the reference documentation, that should come from developers, because it comes from the code
- the usage documentation, that should come from users, because it comes from ways people have found to solve their problems.
Cocoon is probably special in that it's more a toolbox than a well-defined product, and its developers are also its first and most intensive users. But they are special users that don't really need the docs as they've written the code. Hence IMO the fewer itches to scratch to provide better docs to regular users. Also, we write new features to solve our everyday problems, whereas non-devs have to use what we provide them.
This has led to the status of our docs, where lots of users have contributed lots of good wiki pages, but where few devs care to organize this valuable content (and I easily admit that I'm not one of them).
So Cocoon authoring should be wide open to users, under of course the control of devs that should proof-read and validate the content, using a tool that easily allows import into the cocoon.apache.org website (that's not the case of the wiki). Classification will come by itself if docs can be tagged, as although it's easy to write mistakes in the content if you don't know the code well, it's more difficult to attach an invalid tag to that content (unless you do it on purpose of course).
I don't know if that tool should be Drupal or Daisy, but the important requirements from my POV are:
- inline WYSIWYS (what you see is what you structure, i.e. htmlarea or something similar, but no wiki or XML syntax)
- version management, so that validated content can be published on cocoon.apache.org while newer versions are being written
- tagging, to produce the classification of docs and ease navigation
- some management tools allowing to quickly see what has changed and needs to be validated.
Maybe I'm just restating evidences, but that's why would make _me_ more inclined a writing docs.
My 0.02 euros, Sylvain
-- Sylvain Wallez Anyware Technologies http://apache.org/~sylvain http://anyware-tech.com Apache Software Foundation Member Research & Technology Director
