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

[markd at macports.org]

Boey Maun Suang <boeyms at 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