MacPorts guide & Wiki

[Randall Wood]

Why not distribute the guide in a port?

On 22 Jun 2007, at 17:36, Juan Manuel Palacios wrote:

>
> 	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
>
> _______________________________________________
> macports-dev mailing list
> macports-dev at lists.macosforge.org
> http://lists.macosforge.org/mailman/listinfo/macports-dev