Website redesign (was Re: Please clear up DarwinPort/MacPorts confusion)

[Mark Duling]

Juan Manuel Palacios <jmpp at macports.org> on Monday, April 9, 2007 at 11:21
AM -0800 wrote:
>>> But the disadvantage, as opposed to a Wiki, is that joe user can't 
>>> make
>>> changes to the docs. And that is what people want. Although I wonder 
>>> if
>>> we have Joe user contributing to the docs if it will really be 
>>> better. It
>>> may be, I just don't know.
>>
>> I've come across a number of projects using wiki documentation 
>> lately. Lacking any centralized editing, it tends to vary wildly in 
>> quality, substance, and style. Information is poorly organized and 
>> difficult to find, and documentation is often duplicated.
>>
>> Maybe my experiences aren't a sufficiently representative example, but 
>> I've been left with a very poor impression of open source wiki 
>> documentation.
>>
>> -landonf
>
>
>	One solution to this problem I was thinking about is a middle ground 
>between requiring coding skills to allow you to edit a doc (if you have 
>them, logic tells me you already hold a macports commit bit and 
>therefore can edit the Wiki already.... or are not afraid to delve into 
>Dockbook sources ;-) and giving access to everyone (open season on our 
>Wiki, anyone can edit): said middle ground could be a WIKI_EDITING trac 
>permission setting (or whatever to that effect) we could hand 
>selectively to those who've proven an at least acceptably high 
>knowledge of MacPorts; said people need not be skilled enough to commit 
>to our repo and/or know how to edit docbook sources, but should at 
>least be knowledgeable enough to know what they're talking about when 
>writing documentation. We could receive nominations for such people and 
>judge based on their activity on our lists, for instance, and maybe 
>even the Wiki editor status could be seen as a step before gaining 
>commit access to the repo (though not necessarily).
>
>	Thoughts?

Juan,

I think that is a good idea.  I share Landon's concerns but I am also a
little apprehensive of ditching DocBook altogether, because of its
flexibility in getting different outputs.  But I am aware that we hve to
do something to get better docs.  I could if I chose keep a parallel
version in DocBook format, strange as that sounds.  But before much of
anything will likely get written we're going to have to get a
documentation strategy mapped out.  If we get people together that are
interested they could talk it out and present options.  As it is, talking
about docs on the mailing list doesn't work because few people on the list
are interested.

On the other hand, if it turns out we have or want few people that are
able and willing to work on documentation and we don't allow everyone to
edit them, then it doesn't make that much difference what technology we
use.  I'd like to be a lead on the documentation team, and it would
probably be easiest for me personally to just use DocBook.  I could
coordinate wiith and even show a few others how to use xxe if they like,
or if they prefer just to send updates and contributions to me I could do
it.  I'm not trying to backtrack on the Wiki commitment, but I suppose it
is *possible* that we won't have that many documentation contributors and
if so we could go to a lot of work and not get any better docs u til later
down the road, when we might need something that the wiki won't do anyway.
 Perhaps not, I'm just thinking aloud and wondering if kicking the
technical decisions down the road and getting to work on content might be
a faster route to better docs right now.  But i'm happy to go with a
consensus.  I may just being paranoid about a new method.  Thoughts?

One last thing.  Juan, what would you like to see changed in the current
InstallingMacPorts wiki page?  I wasn't sure what you wanted to see happen
there.

Mark