Guide - was ... trunk/doc-new/guide/xml/installing.xml

[markd at macports.org]

>I think most of my ports work on Panther. If they don't, I'll gladly
>take bug reports.
>
>> so how long will it be before in response to a MP
>> developer's suggestion that (at the very least) it is wise to avoid
>> 10.3
>> if possible that we hear: "But on page 1 at the top of the Guide it
>> states
>> requirements for 10.3 (implying it is supported), and now you're
>> telling
>> me it isn't supported?"  And we do say that, and I think we've had
>> this
>> discussion many times before.
>
>Then we should state on page 1 that support for Panther and non-Mac
>OSes is not guaranteed. It is official MacPorts policy that only the
>latest two Mac OS X releases are supported [1] so we should state
>this in the Guide.

For OS X that is not a problem, but what should we say for other
platforms?  If we can agree on something it would be nice to state it.
>
>[1] http://lists.macosforge.org/pipermail/macports-dev/2008-June/
>005393.html
>
>
>Note: The Guide already contains examples of "darwin 7" platform
>statements, which could also be construed to mean that Panther is
>supported.

That seems a stretch.  I think removing all reference info to 10.3 (and
then I suppose the Portfile keywords too?) would amount to "cutting off"
support, which seems draconian.
>
>
>I do think it is a good idea to list the requirements of MacPorts in
>the Guide, and certain versions of Xcode are required. This came up
>before, and it was decided that we would gladly trade user time for
>developer time -- better to have the user spend time downloading a
>new Xcode than to have a developer spend time to figure out that a
>user's problem was caused by an old Xcode.

Agreed.  But you're claiming you've solved the problem by listing version
numbers in the Guide and I say you haven't, and there are other problems
raised by this method as well .....

>We are not in control of
>Apple's web sites, but we are in control of the Guide, hence it is
>useful to list there the minimum versions of Xcode that should be used.

....  for example here.  I don't want to give users a reason not to go to
Apple's download sites, because there can be important information there. 
For example, by going to Apple's site as part of this thread I learned
important details about what is in Xcode 3.1 that I didn't know, and that
Apple supports installing Xcode 2.5 on 10.5.  I don't want people looking
at potentially dated information in the Guide (there is no way to avoid
this when updates occur) and Googling for the outdated version listed in
the guide.
>
>I don't like your link to download Xcode 2.5 directly for the same
>reason you didn't like me stating that Xcode 2.5 is the latest
>version for Tiger -- what if it changes? I think it's better to teach
>the user to fish: show them where Xcode releases are posted and let
>them find the latest version.
>
I don't like it that well either but I thought that was a concession to
you, and frankly I'm lost now because I think you've taken my view now not
to list version numbers unless absolutely necessary.  I thought it a
reasonable concession since I'm more concerned that the current OS Xcode
version not be listed since that version will change soon and frequently,
than with a previous OS (Xcode version) that won't, and might not at all.
>
>> But look, I know I'm acting as a self-appointed documentation Nazi,
>> and
>> probably  coming off as too argumentative,
>
>No worries -- I'm glad someone feels responsible for guiding the Guide!
>
>
>> but the truth is I think there
>> are unstated assumptions at work in discussions about the Guide.  I
>> think
>> failure to observe a certain rules ruins a document over time, and
>> that
>> disagreement on those implicit assumptions is the source of most of
>> the
>> disagreements on MP docs.  I have several in mind:
>>
>> 1) One I'm always pushing is basically the 80/20 rule (or 95/5 or
>> insert_your_own_numbers here).  We have a mailing list, and it will
>> always
>> be used and needed, and a wiki.  Some questions are best answered
>> by the
>> list, and trying to answer certain questions that fall in the 20%
>> in the
>> Guide will destroy it over time.  The Guide is an attempt to document
>> certain things, not everything.  A document can't be all thing to all
>> people.
>
>I believe the Guide should document everything you need to know about
>using MacPorts. I would not include information about how to use any
>specific port, and I wouldn't include ProblemHotlist-type stuff which
>is really just descriptions of bugs which will be fixed.
>
And if wishes were horses, beggars would ride.  "Document everything you
need to know" is an impossible goal.  If this were really true, we'd shut
down the mailing list.  It is a meaningless statement in practical terms. 
"Make the Guide as good as we can make it" is better, and may not include
certain things you might want to know if the Guide is not the best medium
to deliver those things.
>
>> 2) No duplication of text unless absolutely necessary.  This is a
>> volunteer project and we must minimize the effort required for
>> documentation, or it will seem futile to have good documents in a
>> reasonable length of a volunteer's time.  Soon, in a future
>> release, the
>> man pages will be sourced oet of the Guide and this is a big step in
>> having accurate and maintainable documents.
>
>Before manpages can be sourced out of the Guide, the information
>currently in the manpages needs to be put into the Guide... :)

The reference section of the guide contains the manpage sources. 
http://guide.macports.org/#reference

Important parts are still missing, but completion is not far as far off as
you think.  The reason it  takes so long is that I am re-writing it, and
I'm trying to make it accurate as I go.  If you think the current manpages
are accurate, compare the Guide section on startupitems with the manpages
on that topic.
>
>Also, I pointed out recently how much duplication of text we already
>have, which is captured here:
>
>http://www.macports.org/docs.php

Yes, I know that.  This needs to be fixed, not perpetuated as a model.
>
>
>> 3) Minimalism is good, because people only have so much time to read.
>> Everything that can be said shouldn't be.  All text needs to
>> support the
>> main purpose of the document.
>
>That's true.
>
>
>> I think probably we should hash out this stuff as a community, and I'm
>> always willing to submit this sort of thing to a vote.  I think a
>> certain
>> ruthless adherence to these principals will get us a better Guide
>> in the
>> end since comprehensive documentation is difficult and none of us
>> get paid
>> for this.  I can look at almost any part of the Guide and think "That
>> could be a lot better", but I think when trying to do so I think there
>> should be overall consideration of the document design principles.
>> BTW, I
>> do intend to start in on the unfinished sections of the Guide very
>> soon,
>> and also address the tickets on it.  Hopefully in a matter of weeks.
>
>Are the document design principles documented somewhere? :)
>
No, but I thought the last email could be a starting point so I'm saving
that info as a start at least.
>
>>> I agree "as of this writing" isn't good without a date, and that I
>>> shouldn't have created the situation where we have to update the
>>> Guide with "latest" information about Xcode releases, even if they
>>> are infrequent. Instead, how about we list a minimum Xcode version?
>>> The minimum supported Xcode version for MacPorts is 3.0 on Leopard,
>>> 2.4 on Tiger and 1.5 on Panther, as seen in the MacPorts configure
>>> script:
>>>
>>>
>>> case "$XCODE_VERSION" in
>>>   1.[[0-1]]*|2.[[0-1]]*)
>>>     AC_WARN(This version of Xcode Tools is not supported)
>>>     AC_WARN(Please upgrade at [ http://connect.apple.com/
>>> ]http://connect.apple.com/)
>>>     ;;
>>>   1.[[2-4]]*|2.[[2-3]]*)
>>>     AC_WARN(This version of Xcode Tools is out of date)
>>>     AC_WARN(Please consider upgrading as some ports fail compiling)
>>>     ;;
>>>   1.5*|2.4*|3.*)
>>>     dnl Supported version
>>>     ;;
>>>   *)
>>>     ;;
>>> esac
>>
>> I prefer to let the scripts do their job and warn the user
>> appropriately
>> without duplicating the script messages in the documentation.
>> Principal
>> #2.  :)
>
>The problem is that the script in which this is implemented is the
>configure script, which is not a script a user will encounter if
>installing MacPorts the usual way, from a dmg. Getting MacPorts to
>check the Xcode version during normal use is an as yet outstanding
>ticket.
>
>http://trac.macports.org/ticket/12794
>
I see.  Well maybe there should be a principle #4, that transitory
information in the guide should be limited, and if a bug or incomplete
feature that would solve user issues isn't a top priority for the base
developers, then maybe it isn't for the doc team either and the mailing
list may need to suffice.  ;-)
>
>
Mark