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
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@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo/macports-dev
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.
On Jun 22, 2007, at 18:13, Randall Wood wrote:
Why not distribute the guide in a port?
Why is that a good idea? I read Juan's message as being about encouraging people to create and update the documentation. We already have mechanisms for making it available to people -- export to HTML and put on web site. That's certainly where I would expect the documentation to live. Why do you want it suddenly distributed as a port?
On 27 Jun 2007, at 02:45, Ryan Schmidt wrote:
On Jun 22, 2007, at 18:13, Randall Wood wrote:
Why not distribute the guide in a port?
Why is that a good idea?
1) It is eating our own dog food. Distributing it by port means that it could be bundled with the .dmg installer and updated through the regular port sync ; port upgrade outdated mechanism. 2) There is a makefile for building the documentation from the XML source already. Unfortunately it does not work right now, but I think that it should be fairly trivial to get it working again. 3) The guide never migrated from the opendarwin.org servers. We haven't had it on the web and there is an open ticket for the ability to write static documents in wordpress on macosforge.org that is still unaddressed after 9 months.[1] MacPorts controls the port distribution chain in a way that we don't control the macosforge.org site.
I read Juan's message as being about encouraging people to create and update the documentation. We already have mechanisms for making it available to people -- export to HTML and put on web site. That's certainly where I would expect the documentation to live. Why do you want it suddenly distributed as a port?
I don't care if it is on the website or in a port, I just want it. If we can get it out in a port faster than we can get it on the site then we should use a port to distribute it. References: [1] https://svn.macosforge.org/projects/macports/ticket/10666 Randall Wood rhwood@mac.com http://shyramblings.blogspot.com "The rules are simple: The ball is round. The game lasts 90 minutes. All the rest is just philosophy."
On Jun 27, 2007, at 5:38 AM, Randall Wood wrote:
On 27 Jun 2007, at 02:45, Ryan Schmidt wrote:
On Jun 22, 2007, at 18:13, Randall Wood wrote:
Why not distribute the guide in a port?
Why is that a good idea?
1) It is eating our own dog food.
Building MacPorts off the MacPorts Portfile is definitely eating our own dog food... and I can tell you it tastes good! ;-)
Distributing it by port means that it could be bundled with the .dmg installer and updated through the regular port sync ; port upgrade outdated mechanism.
Figuring out how to bundle it with the dmg is definitely a good thing, I think, but making it available in such a way that "sync" and "selfupdate" keep it up to date is probably more trouble than it's worth. I see some potential approaches, none of which convince me at all that much: -) Create a port that fetches the xml sources from svn: you'd need a maybe hefty list of dependencies (to generate the html files) for something that's otherwise just a couple of clicks away through a web page; -) Create a port that fetches the already regen'd html files: involves developing the regen methodology server side and making the html files available somewhere for fetching (our svn repo is of course an option); In both of these cases you'd have to come up with a versioning scheme for the guide in order for our regular sync/outdated/upgrade procedures to work with this port, but that's admittedly easy (the version number could simply be the regen date timestamp, yyyymmdd -- including hourly information as the Portfile revision if more than one regen takes place in single day, probably--). -) A third and ugly alternative could be including the html guide as MacPorts sources, ${prefix}/share/doc/macports path (./configure's -- docdir option), but obviously there's a lot of Q/A to do for this option to be viable and smooth, and I just don't think it's worth the effort. However, if you feel motivated enough to explore any of these options (or any other you might have and which I'd love to hear about), then please do not let me stop you! The more (consistent) documentation we have and the more venues to access it, the better.
2) There is a makefile for building the documentation from the XML source already. Unfortunately it does not work right now, but I think that it should be fairly trivial to get it working again.
It does work, you just need to run the base/configure script before delving into the guide's Makefiles.
3) The guide never migrated from the opendarwin.org servers. We haven't had it on the web and there is an open ticket for the ability to write static documents in wordpress on macosforge.org that is still unaddressed after 9 months.[1] MacPorts controls the port distribution chain in a way that we don't control the macosforge.org site.
I'll look at the ticket and make my comments, sorry for not addressing it in such a long time! And it's true that we don't control our website in the same way we control our base sources and ports tree, but it's also true that we've had a very good communication and co-existence with the entire MacOSForge community since we've been here, so I'm confident we'll be able to come up with a good enough plan to revive the guide (it hasn't been done until now simply 'cause no one dedicated any real time to it until now, including me).
I read Juan's message as being about encouraging people to create and update the documentation. We already have mechanisms for making it available to people -- export to HTML and put on web site. That's certainly where I would expect the documentation to live. Why do you want it suddenly distributed as a port?
I don't care if it is on the website or in a port, I just want it. If we can get it out in a port faster than we can get it on the site then we should use a port to distribute it.
As said above, would love to see real work initiatives materialize in tangible results, so do not let any of us block you in any way from producing them! In the mean time I'll keep on pushing for a guide web space.
References:
[1] https://svn.macosforge.org/projects/macports/ticket/10666
Randall Wood rhwood@mac.com http://shyramblings.blogspot.com
Thank you for your interest and energy, much appreciated! Regards,... -jmpp
Hi Juan (and everyone else), Sorry for the delay in replying, and the low comment-to-quotation ratio; I thought I'd best leave the original context in.
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 think that that was the consensus approached in a previous discussion on the mailing list (though I haven't found it yet), and in any case it seems the most reasonable breakdown to me.
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.
That all sounds pretty reasonable to me, and again, I think that that was what had been previously suggested.
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.
Well, it looks like you've started the fire, so we just need to keep fanning the flames! Kind regards, Maun Suang -- Boey Maun Suang (Boey is my surname) Email: boeyms at macports dot org
On 28/06/2007, at 04:16, Juan Manuel Palacios wrote:
On Jun 27, 2007, at 5:38 AM, Randall Wood wrote:
On 27 Jun 2007, at 02:45, Ryan Schmidt wrote:
On Jun 22, 2007, at 18:13, Randall Wood wrote:
Why not distribute the guide in a port?
Why is that a good idea?
1) It is eating our own dog food.
Building MacPorts off the MacPorts Portfile is definitely eating our own dog food... and I can tell you it tastes good! ;-)
Not only that, but it means that you can have the official documentation with you while you're offline, and that can be surprisingly useful for a multitude of reasons (or even a potential lifesaver if you need to fix something and your networking is broken -- or just ran out of money on casual wireless overseas). I'll have a think and tinker with the three documentation packaging suggestions from Juan, and let you all know if/when it gets anywhere. Kind regards, Maun Suang -- Boey Maun Suang (Boey is my surname) Email: boeyms at macports dot org
participants (4)
-
Boey Maun Suang
-
Juan Manuel Palacios
-
Randall Wood
-
Ryan Schmidt