MacPorts guide & Wiki

[Juan Manuel Palacios]

	Hey Maun Suang!

	Your recent work on the guide has caught my eye and made me very  
interested! We've been trying to revive such an important  
documentation effort for a while already with many false starts, so  
first off I want to thank you for taking a real lead in it!

	Landon and I have been talking about putting the guide back up on  
our site once again even if it's not fully up to date, and start  
improving it little by little, baby steps, 'cause every single  
gigantic effort till this day to provide the project with the  
greatest documentation ever in one fell swoop has failed. Therefore  
baby steps to the rescue, just as you're doing right now! One of my  
explicit goals with this mail is to encourage you to keep on working  
on the guide as your spare time permits you and to assure you that  
your time will not be wasted, at all!

	There are of course the questions of where exactly we'd put the  
generated guide (the html docs) and how we would go about automating  
it's regeneration, which is something I already ping'd Kevin Van  
Vechten on. Once I have some leads from him I'll get back to you and  
this list with details.

	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?

	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.

	Again, I'm really fearing loosing this thread to endless debate once  
again, so I'll go ahead and start with the outlined plan unless  
someone proves me that it is fundamentally flawed because of <insert  
your best possible argument here>. If it happens to fall short of  
ideal, we can always improve it as we move along, but I'm sure we  
would all appreciate at least *some* forward progress on the sorry  
state of our documentation over nothing at all.

	So, people (Maun Suang ;-), start your engines!


-jmpp