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 _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo/macports-dev
