Objection to wikifying the guide
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
First: I'm happy we have a new guide! And now, to respond to just a few things... On Dec 14, 2007, at 15:49, markd@macports.org wrote:
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.
In general, that'd be great. Consistent documentation written with goals in mind is awesome.
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.
Was there an off-list discussion about using a wiki instead of docbook? I'm happier with docbook I think.
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
What's the objection to version numbers? I think it's useful to use specific Mac OS X version numbers, since users should be informed that MacPorts works great on Tiger, is going to work great on Leopard once we iron out the bugs, should still work ok on Panther, and is probably not going to give great joy on Jaguar or earlier. As to MacPorts version numbers, if you don't want to mention them, what version of MacPorts do you want to document? The currently- released one? trunk? Either way, the guide should probably say, at the beginning somewhere, which it is.
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.
I should probably speak to this too, as I frequently make such comments that such and such should be documented. I guess I see the guide differently: I think it should be our Bible, our one canonical document, telling you most everything you need to know about using MacPorts, developing portfiles for MacPorts, filing bugs about MacPorts, contributing in other ways. One thing I would not have in the guide is information about specific port bugs, such as we have in the Hotlist or to some extent the FAQ.
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.
Tangentially related to the comment of Apple vs. Dell documentation: we should adopt a style guide of some sort for our guide, and I might suggest that using the Apple Style Guide would be a good idea, at least as a starting point. It's available here: http://developer.apple.com/documentation/UserExperience/Conceptual/ APStyleGuide/AppleStyleGuide2006.pdf
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.
participants (2)
-
markd＠macports.org
-
Ryan Schmidt