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
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ macports-users mailing list macports-users@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo/macports-users
