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

Nico Kadel-Garcia nkadel at gmail.com
Sun Apr 1 15:11:16 UTC 2007


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.





More information about the Sussex mailing list