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.
_______________________________________________
macports-users mailing list
macports-users@lists.macosforge.org
http://lists.macosforge.org/mailman/listinfo/macports-users
