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

[Nico Kadel-Garcia]

Nic James Ferrier wrote:
> "John D." <johnsemail at f2s.com> writes:
>
>   
>> Other failings, or maybe just frustrations, are that while the linux world has 
>> some truely brilliant people, who code, develop etc etc, they can't write 
>> documents for shit! The concept of projects like TLDP is fantastic, but the 
>> very nature of howto's and other instructional documentation, are that they 
>> should possibly be aimed at the lowest common denominator - rather than 
>> written in nicely formatted nerd/geek. Those are the people who have the 
>> ability/intelligence/whatever to "skip read" the basic english to work out 
>> what it is that they want to actually do and how to do it.
>>     
>
> This *is* something that I wish a lot of newbies would help with.
>   
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.