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

[John D.]

On Sunday 01 April 2007 15:25, Nic James Ferrier wrote:
> 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).
It's one of the reasons that I value the LUG and the moots Nic. I actually 
manage to get hold of "proper techies", that understand (usually) whats going 
on when I, in my ignorance, get answers different to the ones that might have 
been suggested in some sort of documentation.

One of the few places that I have suggested to others with my level of 
knowledge is Gentoo's documentation. A couple of years ago, when I first 
asked about "it", Geoff (Teale) was kind enough to suggest that there might 
be an easier "advanced" distro for me to try - being a stubborn git, I didn't 
listen. 

No-one was more suprised than me, that on my third attempt, I managed to get 
it installed and running (actually Geoff was spot on, because I only ever 
managed to get it installed and running as a "stage 3 + GRP" install - the 
stage 1, 2 and boot strapping where a total mystery). Though I did learn that 
they must have put considerable resources in producing their docs.

I've even emailed Linux Format before now, asking for more "newbie oriented" 
tutorials etc. They probably think I'm thick - hell they're entitled to their 
opinions. While in the 5 or so years of subscribing to the mag, I still only 
understand about half of whats printed (or sometimes it's more than half, but 
it's about stuff that I'm either not interested in or is irrelevant to what I 
want to do).

Of course, I'm well aware that most of what I need to know is either at TLDP 
or in the man pages, but as I already said, TLDP is bad enough, the man pages 
are really the pits (IMO of course). I have to read the link I run in my "LQ 
sig" whenever I need to make use of them! 
(http://www.cs.mcgill.ca/%7Eguide/help/man.html)

I'd be happy to help, except for the lack of reasonably priced 
hotspots/Wimax/mobile broadband - when I'm stuck in some crappy motorway 
services or truckstop (erm about 100,000 miles per annum) and actually have 
some time available. Despite my lacking in a decent formal education, I like 
to think of myself as reasonably well read (depends on someones opinion 
of "well read" though - I doubt that the ability to swear in Welsh counts).

Though I can usually work out if I feel that a howto or similar is IMO, well 
written. I certainly don't have the time to contribute what I'd feel is 
anything like enough to be of any real use - hence my periodic attendance at 
LQ and the others (are you listening to this Camelot ???).

Ah well, I suppose I'll just have to keep moaning ;P

regards

John D.