Objection to wikifying the guide

[Ryan Schmidt]

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