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.
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. Mark