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.