Website redesign (was Re: Please clear up DarwinPort/MacPorts confusion)

[Boey Maun Suang]

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 at fastmail.fm