On Jun 22, 2007, at 16:36, Juan Manuel Palacios wrote:
One other topic is how we should integrate that source of information with the Wiki, and on this I hope to not tread too harshly on what's already been discussed many times before, of which I don't have much track at all to be honest (and I apologize to people involved for that!). In any case, Wiki docs being as dynamic as they are, I was mainly thinking we should use the Wiki solely for "How-To" type of documents, like how to setup a mail server with MacPorts installed software and edit it as new information and packages become available. On the other hand, existing wiki documentation on the basics of how to use MacPorts, how to become a member, how to properly submit tickets, Portfile writing guidelines and the like should be moved to the guide if not already there, officially and emphatically endorsed by the project (not that the wiki isn't endorsed, but the guide seems to me like more formal). Thoughts?
I agree. Formal documentation like how to use MacPorts, how to get started writing portfiles, etc. should be in the official guide. It should be migrated there from the wiki. New material can always start out in the wiki, of course, but should be regularly evaluated to see what needs to be moved to the guide. The FAQ and problem hotlist should probably stay in the wiki though, I think. Those are rather dynamic.
On the contribution topic, there are those with commit bit already (who should feel free to dive in and and work on the official docs, I'm sure peer review will help stabilize things) and those who don't have +commit but still might want to contribute. I see many, many solutions to the latter, so many in fact that I fear this thread getting lost in endless discussion on how to channel it, as it's happened before. I'll start by proposing the following: I create a "Documentation" milestone up in the roadmap, where users can upload either patches and/or comments on the docs (in case they don't know how to create patches) and committers review and apply them as appropriate; those contributors without +commit and with a good record get promoted to project membership. On the wiki side of things, I'll fulfill one of my promises and coordinate with kvv an easier way of granting wiki write privileges to a selected subset of people whom we approve to write wiki documentation, so that "how- to" documents are also fluently created and maintained.
A "Documentation" milestone sounds like a good idea.