On 2/3/06, Jorge Godoy <[EMAIL PROTECTED]> wrote: > > Kevin Dangoor <[EMAIL PROTECTED]> writes: > > > A wiki adds to this the ability to link easily to different articles. > > I wrote a bit about a wiki for software documentation here: > > http://www.blueskyonmars.com/2005/09/27/what-i-want-in-a-wiki-for-software-development/ > > > > I wanted to raise this for discussion and, hopefully, volunteers who'd > > like to work on the app. I am more than 100% booked right now, but an > > app like this would be really helpful. > > > > Thoughts? > > Even though I really like those comments -- and I've even posted some for the > PostgreSQL docs --, one thing that we have to think about is moderating *and* > not starting discussions there. Otherwise we'll end up with pieces of docs > here, there and everywhere (ML, Wiki, Tickets, blogs, etc.). Moderation will > help keeping the correctness of comments and clarifications (doubts should go > to the mailing list and not on the documentation page, it might get something > to make it clearer later...).
Ticket #510: > php.net and plone.org are great example where other developers can put in > relevant clarifications, suggestions. It also encourages the community to > give back and participate in the proj, while maintaining "quality" control > of docs. We're talking about two different things here. Talkbacks on the documentation pages are very useful. Several times on php.net and dev.mysql.com I've found my answer in the talkbacks, and it gets peer review from the other talkbacks on the page. Sometimes the talkback corrects a mistake or omission in the docs. I rarely see talkbacks go off in topics unrelated to the page, and if so the poster is quickly advised where to send his question. The talkbacks *are* considered in the next revision of the docs, and can be deleted when they're fully incorporated or rejected. A blogging tool can work this way since it distinguishes between "official" content and talkbacks. Using a wiki for documentation has its pluses and minuses. It allows multiple people to collaborate on it, so official docs can be composed quickly and extracted to another format. But a general documentation wiki that doesn't contain the official docs and is not highly maintained and organized, like Cheetah's (finally put out of its misery) and quixote.ca/qx never lives up to its potential. The quality of articles is very uneven, important topics are missing, and new and obsolete docs are intermixed without indication. If everybody puts the date and TG version on their pages that helps, but most people won't. The other problem with wikis is every one has a bloody unique syntax, and it's inconvenient to edit large amounts of text in a web browser. -- Mike Orr <[EMAIL PROTECTED]> ([EMAIL PROTECTED] address is semi-reliable)
