Couple of quick comments, I see that thankfully you guys already have a lot of the details sorted out and the ball is rolling! On Jul 12, 2007, at 2:30 PM, markd@macports.org wrote:
Boey Maun Suang <boeyms@macports.org> on Thursday, July 12, 2007 at 10:16 AM -0800 wrote:
Comments still welcome on the Guide so far.
I haven't been through it in detail, but it looks good to me. I haven't thought too clearly about what, if anything, should become of the old guide (I don't know if a separate technical reference is warranted, which seems to be what the old guide leans towards). Perhaps we can post them somewhere and solicit feedback from users as to what they find easiest to understand and use, and what they think ought to be included or restructured.
I really wanted the new guide to serve as technical reference also, at least for now. I wanted the "Portfile Reference" section to be more or less exhaustive. If that should turn out too large then it could be split out into a separate reference, but I'm not sure it will be that large.
My two goals for he new guide was 1) better organization, and 2) more or less exhaustive "Using MacPorts" and "Portfile Reference" sections. The latter to give us a place to stick all the helpful information about keywords and commands that we exchange on the list now, and often forget. Those things should go in the guide but the old guide had no structure to contain them, and I don't think a FAQ is adequate.
First off, and even if it's just a first draft that we can improve as we learn from experience, I'd like to see a single all- encompassing guide too, with a "users oriented" first section and a "developers" section in which we can put all the Portfile reference stuff and others not geared for regular users. If this proves to be hard to manage and a lot of voices raise up asking for a "simple and short user reference", I'm figuring we can always take the contents of the rewritten guide and split them up in two.
As for the source of your guide, which I understand is a DocBook article, would be able to put it into the doc/ part of the repository so that we can look at it? I understand if you'd like to hang onto control of it yourself (saves me some work, for a start :P), but I think it'd be helpful if the source was somewhere that all those interested in the working on documentation could see it.
Here's where I need some advice. I did the new guide as an "article" and in one XML file because that was more familiar to me. Should I switch to a "book" and/or split the XML into multiple files? Anders has reminded me that the copyright information frm the old guide needs to be added back in and I haven't got there yet. Other than that those questions I'm willing to commit it to svn. And I can't fill in the reference sections fully by myself anyway so it does need to be committed very soon. Let me know your thoughts on that.
We spoke about committing to svn and you expressed your thoughts and concerns about it, but I didn't manage to reply at the moment due to a lack of time. In a nutshell, I'd really love to see your work in our tree so that all those willing to contribute can do it in a more timely fashion (I know I would have already contributed three or four fixes if I had access to the sources ;-). But I understand that since you're not amending what we have but actually rewriting it, you prefer to keep from committing until your sources become an actual drop in replacement for what's already there. So how's the following: you write up the new guide up to the point where it can replace to a good extent what we have, even leaving empty certain sections/areas if you have to because you don't have enough information to write it up on your own, and you commit that? Once that's in all of us can dive in and help you complete it. I'm even thinking that for the sections you can't rewrite, but what's in the old guide suffices for them to whatever extent, you can simply copy & paste that into the new sources and write up a marker saying "THIS IS OLD, NEEDS REWRITING!" for contributors to notice. More over, we can all agree to nominate Maun Suang and you "Guide Masters": rather than simply diving in and committing patches to the sources in svn, we instead upload them to tickets in the "Documentation" milestone and you guys, governing that milestone, review them and decide when/how to commit them, rewriting them if need be.
Mark
So, what do you guys say? Does this sound like a good protocol? Regards,... -jmpp