Re: Website redesign (was Re: Please clear up DarwinPort/MacPorts confusion)
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.
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
Hi everyone,
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. 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). Kind regards, Maun Suang -- Boey Maun Suang (Boey is my surname) Mobile: +61 403 855 677 Email: boeyms@fastmail.fm
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
participants (4)
-
Boey Maun Suang
-
markd＠macports.org
-
Ryan Schmidt
-
Sean Fulton