Documentation helping (was Re: [Sussex] Thoughts On Contrubuting to the Community)

[John D.]

On Sunday 01 April 2007 16:12, Nico Kadel-Garcia wrote:
> Nic James Ferrier wrote:
-----%<-----
> Amen. I highly recommend Eric Raymond's rant about open source GUI's at
> http://www.catb.org/~esr/writings/cups-horror.html, and his guidelines
> at the bottom about how to make them usable. (He added some additional
> guidelines I sent him after he wrote it, ones I wrote when I was feeling
> a bit miffed about CUPS management tools myself.)
>
> For a most excellent example of good documentation, especially
> documentation that actually answers the Frequently Asked Questions
> instead of merely answering the questions the authors wished anyone
> cared about, I highly recommend the Subversion manual at
> http://svnbook.red-bean.com/. *THAT* is how to write documentation.
>
> > Speaking as a techy (oh no! I'm going all arrogant again) I find it
> > really hard to imagine audience. It's much easier if you've got people
> > who can give you feedback and say "I don't understand that".
>
> Yeah. That's why I like a really good, not completely technical manager
> to help me negotiate for resources or help me set priorities.
>
> > Maybe part of the problem there is the nature of the documents. If the
> > documents were written with a tool that allowed people to give better,
> > more specific feedback it would be cool.
>
> Wiki's have really taken off for this. Unfortunately, there are so many
> very, very bad Wiki tools out there that it's hard to manage them all.
Ok, that gives me something else to read, thanks Nico. I have enjoyed a couple 
of other bits that "ESR" has apparently written, and even found them 
helpful - in the broader sense of trying to understand "stuff".

Do you mean by "very, very bad Wiki tools", like how the abysmally designed 
Wikipedia is just hideous to navigate/negotiate ?? or have I missed the 
point ?

regards

John D.