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

[Nic James Ferrier]

"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.

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".

When I'm explaining things to people it sometimes takes many attempts
before they get it. But if both sides have patience (and I'm pretty
patient) one gets there in the end.

The trouble is, as far as documentation goes, we don't have a lot of
people saying "I don't understand that I'll help you make it better".


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.

But I'd urge everyone who has tried and failed to understand a TLDP or
any other doc to work out if they can't spend 5 hours with the author
of the document talking on IM about how to make it better. I bet the
authors would love it (I know I would for the stuff I write).

-- 
Nic Ferrier
http://www.tapsellferrier.co.uk