The Guide - again

[markd at macports.org]

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

Well I followed the rules along with everybody else.  I contributed ports
until somebody got me commit rights because they could see I was
contributing ports regularly.  After awhile I closed dozens of bugs on
Trac (eventually hundreds) and somebody gave me bug commit rights on trac
so I could be more efficient at what I was already doing.  Why should it
be any different for the doc team?  Pointing out missing parts that we're
very aware of isn't enough.  Especially since I'm dying to finish it soon.
 :)
>
>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.

We need people who can deliver.  All these pieces are missing as you say,
and I know this quite well.  They are missing mainly because I stopped
mid-rewrite to work with Simon@ to get a single source solution so that we
wouldn't have to write and maintain duplicate information it multiple
places.  I will resume and complete it this summer, but it was the right
thing to do to stop and make it so that our documents and man pages would
match precisely and elininate wasted effort, even though it prolonged the
process.

Many of those tickets say "the guide should ..." and give not a lot of
helpful information.  Not all.  Ryan's doc tickets are particularly
helpful I should say.  But as an example of ones that will linger:
http://trac.macports.org/ticket/15784   Since the creator didn't give any
directly usable information, it will be awhile before that gets acted on. 
Pretty much the same for any tickets as far as I can tell.  So I don't see
why these outstanding doc tickets make such great supporting evidence of
your assertions that the current system is broken.

Mark