As you guys say, having "general comments" space below the docs, with enough visual seperation that its clear that what follows are *NOT* part of the official docs - would lower the invisible "I'm not confident enough to edit what the original dev says about this egg" barrier (I know that holds true for me, at least).
However, unless usage of this feature somehow got over "critical mass" (as cpanratings.perl.org
has), I reckon that it too might be less used over time - reducing its usefulness.
Whats our most used forum for discussion, comments, questions on usage, etc? The chicken-users mailing list.
How about, in addition to the above (which *is* a good feature, and doesn't really have any downsides), we also start auto-cross-linking some relevant threads from chicken-users to the egg docs. Something like this?
Look for threads on chicken-users which *END* with . Reserve this closing set of brackets for a freeform list of tags.
Mails whose closing tags contain "egg", "usage|tip", and the *exact* name of an egg mean that that thread should be auto-linked on the egg doc page.
"blah blah blah [egg usage awk]" => add to egg docs
"blah blah blah [egg tip awk]" => add to egg docs
"blah blah blah [egg snippet awk]" => add to egg docs
Perhaps also (this is seperate from the specific topic at hand, so perhaps ignore this part):
"blah blah blah [egg build awk]" => triggers an email to registered egg dev's (a global list of devs, plus an egg-specific one)
So how would crosslinking look like on the web page? At a minimum, we have the Message-ID, so (taking Alarics last mail as an example):
Newcomers to chicken would have one page where they can look at the docs, comments, and also specific threads from the mailing list which talk directly about the egg.
There would be less of the dreaded "search the list, there was something on there 6 months ago about the egg you're having trouble with, but I forget exactly what it said...."
No-one has to change their patterns of interacting with the community. There's no seperate step of updating a wiki page. Its all just mail. You can imagine a scenario where a thread organically grows into a discussion of how to best use a particular egg.
(eg: thread starts with a question about why this code is failing. Thread continues with a suggestion to use this other egg instead. Some features are explained which weren't obvious from the egg name or egg docs)
Instead of someone now having to make yet another todo item (because we know you don't have enough of them already) to add some of this info to the wiki, you just add the tag to one of your follow up posts to that thread.
Presto, its attached to the end of the egg docs.
Well, while we're brainstorming and all ....