New Howto

[Ryan Schmidt]

On Jun 5, 2008, at 19:32, Jordan K. Hubbard 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, trac.macports.org and guide.macports.org  
>> (and the upcoming MPWA at 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 going to disagree with you too, Jordan. Then again, I'm German  
too... Hmm... :-)


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

Ah, I didn't understand at all from your original post that you were  
thinking of a larger scope than MacPorts, so thanks for clarifying that.

Still, I like that we have documentation on how to set up the PATH  
for MacPorts, not just a general document on the PATH that lacks  
MacPorts specifics. And I like that we're getting how-tos which tell  
you how to do things with MacPorts that people frequently ask how to do.

I think MediaWiki is a fine wiki engine. It's the wiki system I use  
for myself personally. At the time I set that up, I liked its wiki  
syntax best. But I think a more important consideration is that we  
already have a wiki system in Trac. We should not now add another  
wiki system with a conflicting syntax. If we wanted to switch from  
Trac wiki to MediaWiki we could discuss that, but converting all  
existing content could be difficult (though maybe someone's already  
written an importer; I haven't looked).

I'm in fact in favor of separating MacPorts further from Mac OS  
Forge, not joining it further by creating a consolidated  
documentation space. For example, I'd like to get the links to the  
other Mac OS Forge hosted projects off of the MacPorts Trac web  
pages; IMHO they have no place there. As a MacPorts user, I really  
don't need to know that Mac OS Forge also hosts Bonjour,  
BridgeSupport, CalendarServer, etc.; If I want to know that I can go  
to www.macosforge.org.


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

Oh. Right. :-)