The Guide - again

[Ryan Schmidt]

On Mar 8, 2009, at 13:00, Rainer Müller wrote:

> Ryan Schmidt wrote:
>>> Especially if the concern is the guide being outdated, I see the
>>> problem
>>> in the guide format. We had the recent discussion to move the  
>>> guide to
>>> another markup language but it was teared down. What else can we  
>>> do to
>>> attract more people for writing documentation?
>>
>> We don't want more people writing the Guide. It should stay as a
>> coherent document authored by one or a few individuals who have a
>> handle on the whole thing.
>
> I want more people writing the guide :-)
> At least I count some TODOs in the guide which are probably there  
> for as
> long as I use MacPorts.
>
> Missing/Incomplete:
>  * Some Tcl extensions
>  * Global variant descriptions
>  * /usr/local and its breakage
>  * More about port groups
>  * portindex
>  * *-devel ports
>  * It needs to be synchronized/merged with InstallingMacPorts [1] and
>    UsingMacPortsQuickStart [2].
>
> For most of these items have corresponding Trac tickets [3], some of
> them older than a year.
>
>> From this list it is clear for me that the current team of guide  
>> editors
> is not able to catch up. Don't understand me wrong, I appreciate the
> time investment and contributions from anyone, I just think we need to
> make it possible for more people to contribute to the guide.
>
> The open source contributors count on Mac OS X is very low in my
> opinion, so in order to attract more contributors we need to lower  
> barriers.

Yeah. The Guide could also use some cleanup and clarification,  
probably all over. The problem is those of us who have been with  
MacPorts since before the Guide was written don't have much reason to  
read it, so we don't notice what's wrong or unclear or missing in it.