MacPorts guide & Wiki
rhwood at mac.com
Fri Jun 22 16:13:04 PDT 2007
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!
> macports-dev mailing list
> macports-dev at lists.macosforge.org
More information about the macports-dev