New Howto

[Ross Walker]

On 6/5/08 8:32 PM, "Jordan K. Hubbard" <jkh at apple.com> wrote:

> 
> On Jun 5, 2008, at 4:58 PM, Rainer Müller wrote:
> 
>> We already have spread our website over enough different places. There is
>> macports.org <http://macports.org> , trac.macports.org
>> <http://trac.macports.org>  and guide.macports.org
>> <http://guide.macports.org>  (and the upcoming MPWA at db.macports.org
>> <http://db.macports.org> ). It is already hard enough to find the relevant
>> information one is looking for. If we now add yet another new site, this will
>> become even worse.
> 
> Rainer, I'm beginning to wonder if you just like to argue.  I know, the
> thought of a german who likes to argue - it's almost impossible to conceive
> of, isn't it?  :-)
> 
> I was thinking of a somewhat broader problem space than just MacPorts here,
> given that the notion of writing "howtos" ultimately and logically extends
> well beyond just the software you choose to add explicitly yourself.  There
> are also other projects on macosforge who would like to see their own howtos
> on various topics, some of which are essentially meta-topics ("you must know
> foo before you can understand bar, even though foo is not logically in the
> domain of what we are doing").   Rather than have multiple people re-write
> howtos like "The Unix PATH and how it affects you", it would therefore be
> better to have a group of documentation-centric people who maintain howtos (or
> mediawiki pages) like that, whether or not they're also members of the
> macports project (or the ruby project or the webkit project) being essentially
> irrelevant as long as they can write good docs.  There's no rule that says all
> developers have to be in one and only one project, or that all projects have
> to force all URLs into a single domain in order for people to find stuff.
> From my perspective, knowing I can go to http://howto.macosforge.org or
> http://doc.macosforge.org, or whatever the heck we might decide to call it,
> and find all the docs that the various projects are publishing seems to make
> it a lot EASIER to find the information I am looking for rather than the
> opposite.
> 
> More to the point, if we feel it's appropriate to have a general documentation
> project on MacOSForge, we're going to create one regardless of what macports
> decides to do since we have plenty of meta-topics to cover, including but not
> limited to general rules of the road for open source collaboration, how to use
> MacOSForge itself, etc etc.   In comparison with that, splintering the docs
> into different domains and documentation formats seems a lot more confusing to
> me as well as having the potential to turn away contributors who would like to
> write end-user tutorials on using popular software but don't actually use
> macports.   What's been done in macports so far represents an excellent start,
> don't get me wrong, but it's also raising the question as to whether or not
> it's happening in precisely the right project context and/or using the right
> tools.
> 
> In any case, there's little point in arguing about this since the bigger
> picture goal here is going to evolve independently of any argument you or I
> might have anyway, so I think both you and I can save our fingerpads this time
> around.

Jordan,

I was pleasantly surprised to see you on the list as I remember you way back
from my FreeBSD list days.

Anyways I think what needs to happen first is to decide what should be
MacOSForge and what should be MacPorts and split the documentation
appropriately.

Maybe restrict the documentation on MacPorts to just the documentation on
how to use MacPorts, how to develop ports for MacPorts and how to
troubleshoot repair a broken MacPorts tree and put the appropriate OSS
project how-tos under MacOSForge.

You can always create out-of-wiki links between the two.

It's probably not the most thought out approach but my wife is talking my
ear off while I write this...

-Ross