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