Objection to wikifying the guide

[markd at macports.org]

I am going out of town tomorrow and I may not be able to participate fully
in this conversation until three weeks hence, but I feel the need to set a
discussion that has begun privately before the community.  I think that
major changes to the guide, should be done only after the doc team has
properly considered it.  simon@ has been and is doing major changes, but
we have been coordinating together on major commits and I think we are on
the same page as far as goals.

I rewrote the guide from scratch for a reason, and I also think a
consensus was reached that the guide would be better served by XML/DocBook
rather than a wiki mainly because editorial control was exercised over it
so a consistent vision would be enforced throughout (other important
benefits were I think tangential).  But there is a use for wikis
nonetheless, and I thought we'd still be using one.  The guide cannot be
all things to all people, or it might as well be on a wiki.  I don't think
any particular text string "should be in the guide", any more than an iPod
must have an integrated FM tuner.  Adding text for various individual
purposes to meet individual goals without consideration for the overall
purpose of the guide will result over time in a guide that pleases no one.

I do not think that portmgr@ requests for specific changes to the guide
trump the editorial control of the doc team.  Aside from the question of
editorial control, I object to the following practices without a decent
argument.

- adding new technical terms without a value to our target audience
- fragmenting it (or parts of it) into explicit "advanced/non-advanced"
titles unnecessarily
- explicitly referencing version numbers unneccessarily in the guide, be
it MacPorts, Mac OS X, or any other

The frequent argument that this or that text string "needs to be
somewhere" is not adequate because "somewhere" should not automatically
mean the guide.  The guide was meant to be one of our documents, but not
the only one.  Besides which, as a MacPorts member, I reserve the right to
argue for changing the terms, script names, etc. that the portmgr@ team
has used for MP base and installer code to harmonize them with plans for
the guide.  I intend to argue for at one such change to MP base for this
reason in January.  Error message (and other terms introduced by code)
consistency with other elements of a project is a hallmark of the
difference between a Mac and Windows.

This is not a question of being territorial, but a question of principle. 
I didn't state the principles I was operating on clearly upfront (other
than to call it a "minimalist guide") because I was the sole author at the
time.  But I think the user experience of accessing the guide is very
important, so that what is communicated and how should be closely
controlled.  Pick up an Apple manual and compare it to Dell's docs.   I'm
not saying the guide meets that standard, but we're trying to lay the
groundwork so far as it is possible given the nature of the project, and
we'll definitely fail without strictly adhering to some principles.

I had hoped to put off requiring patches in Trac for guide changes until
the guide was "feature complete", but I'll gladly do that, and adhere to
it myself, rather than see the guide wikified by requests from portmgr@
that aren't in keeping with the original design goals of the guide.  I
want to see, and offer, competing visions of major guide additions (when
available) before they are committed.  I'll have to submit my competing
vision for the changes required by MP 1.6 in early January after the fact.

Mark