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

[Ryan Schmidt]

On Apr 9, 2007, at 22:58, Mark Duling wrote:

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

I'm still not voting one way or another w.r.t. wiki vs. docbook. But  
I will note that the formatting of the old DarwinPorts manual was  
fairly beautiful, while what comes out of a wiki isn't always. I  
share Landon's concern that wiki-based documentation often seems,  
indefinably, to be of lesser quality than other documentation. Things  
like the Subversion Book ( http://www.svnbook.org ) make a very good  
impression on me. I believe they use docbook as well. But probably  
the main reason that book is of high quality is that it is written,  
or at least checked, by editors. Anybody can contribute by sending  
patches to the mailing list, but the editors are there to watch every  
change and fix any wording weirdness before it ever gets into the  
sources. And that's very useful. But I'm not sure if we have anyone  
here willing to act as such an editor for the new MP docs.

But, if we go with something other than wiki for the MP docs, then  
I'm not sure what the function of the wiki is. For example,  
InstallingMacPorts is surely a topic that should be covered in  
sufficient detail in the MP docs, and if the docs aren't wiki-based,  
then we surely don't need a wiki page describing the same thing.