Juan Manuel Palacios <jmpp@macports.org> on Monday, April 9, 2007 at 11:21 AM -0800 wrote:

...

...

But the disadvantage, as opposed to a Wiki, is that joe user can't make changes to the docs. And that is what people want. Although I wonder if we have Joe user contributing to the docs if it will really be better. It may be, I just don't know.

I've come across a number of projects using wiki documentation lately. Lacking any centralized editing, it tends to vary wildly in quality, substance, and style. Information is poorly organized and difficult to find, and documentation is often duplicated.

Maybe my experiences aren't a sufficiently representative example, but I've been left with a very poor impression of open source wiki documentation.

-landonf

One solution to this problem I was thinking about is a middle ground between requiring coding skills to allow you to edit a doc (if you have them, logic tells me you already hold a macports commit bit and therefore can edit the Wiki already.... or are not afraid to delve into Dockbook sources ;-) and giving access to everyone (open season on our Wiki, anyone can edit): said middle ground could be a WIKI_EDITING trac permission setting (or whatever to that effect) we could hand selectively to those who've proven an at least acceptably high knowledge of MacPorts; said people need not be skilled enough to commit to our repo and/or know how to edit docbook sources, but should at least be knowledgeable enough to know what they're talking about when writing documentation. We could receive nominations for such people and judge based on their activity on our lists, for instance, and maybe even the Wiki editor status could be seen as a step before gaining commit access to the repo (though not necessarily).

Thoughts?

Juan, 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. Mark

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

Boey Maun Suang <boeyms@fastmail.fm> on Tuesday, April 10, 2007 at 7:18 PM -0800 wrote:

...

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.

This sounds good to me; it might also be useful to have a user- contributed wiki section, separate from the official documentation, and from which things could be rolled into the official documentation if the documentation maintainers deem it appropriate (with appropriate notes on the wiki about the rolling-in, of course). I imagine that this scheme would need a bit more of a site re- structure, though, as two levels of permissions on documentation will then be needed.

I agree. I think this approach would be a good compromise. It doesn't stifle people who want to key in what they just learned, but it doesn't mean stuff gets thrown in without consideration proper order either.

As for the official documentation, I would definitely prefer DocBook over a wiki as the format of choice, primarily for practical reasons that grow out of the technical ones previously mentioned. Firstly, the separation of semantic content from presentation should make it easier to produce accessible website content in accordance with the W3C WAI guidelines (http:/www.w3.org/WAI/). Secondly, the ability to easily generate multiple document formats would mean that we could generate both a wide variety of formats to suit the accessibility preferences of various users, and also documentation formats suitable for offline use, which would a boon to people like me who, for technical or financial reasons, don't always have internet access when they have problems using or coding on MacPorts.

I think that it would definitely be worth having a few people leading a documentation effort, as I for one chose to go with DarwinPorts (as it then was) in part because of the quality of the documentation to a newbie (as I then was; I like to think I'm not anymore). I'm not sure that, were I a newbie now, I would be confident enough to try MacPorts given the current state of the documentation. Unfortunately, I won't be free enough to help lead such an effort for at least three months, but I would certainly take part in any effort to get our documentation right (including updating the various Docbook-related ports, which I am currently trying to do).

I know one writer who was positively impressed by the look and feel of the MacPorts site and switched partly because of the positive impression. It is more elegant and clear than the old DarwinPorts site I think, and also Fink's. But I suspect the docs won't benefit the same way if we use the Wiki as a document repository. That's great if you're working on the DocBook related stuff. It needs it, though I've been using other tools, namely XMLMind for editing and their XFC GUI utility for transformations. I haven't used any command-line stuff for DocBook yet. Mark