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

[Sean Fulton]

On Apr 10, 2007, at 2:32 AM, Ryan Schmidt wrote:

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

If you go the Docbook route you could also have the docs on the Wiki  
or Wordpress and allow anyone to comment on them, not change them.  
Some good examples of this approach are the PostgreSQL and PHP docs.

This might be the best of both worlds. Doc editors can get feedback  
and help from user comments. Users don't have to understand docbook,  
svn or trac tickets.

	Sean
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 2436 bytes
Desc: not available
Url : http://lists.macosforge.org/pipermail/macports-dev/attachments/20070410/3bfadf69/smime.bin