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, [EMAIL PROTECTED] wrote:
Boey Maun Suang <[EMAIL PROTECTED]> 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
_______________________________________________
macports-users mailing list
[email protected]
http://lists.macosforge.org/mailman/listinfo/macports-users
