[This is a reply to this but I think I've hit on a Simple Plan here and didn't want it buried in a comment thread]
The docs are okay. They're not great, just okay. But its not the result of a deep disconnect from the user base, a feeling that the docs are Stunningly Good, or a bunch of grey-bearded p5p programmers not remembering what its like to be a newbie. There is a good share of all that going on to be sure, but its not why the docs can be a bit hard on the uninitiated.
Its a result of lots of individual patches adding new information without an overall strong editor. This is an okay way to produce a reference, but not a great way to write a good tutorial. However, its cheap and easy. This is simple Laziness and there's not much we can do to stop it.
There's also a lot of leftover shell, Unix and C legacy in the docs from back when it was assumed that Joe Perl User already knew some basic C, shell and Unix commands. There's lots of statements like "this works just like the C function...". That used to be adequate. Its not anymore. I, for one, am not a C nor a shell programmer, but five years ago almost everyone in Perl was.
Good programmers are often not great writers. In fact, for many of the folks who do the really hard work on p5p, English is their second language. I don't expect the guys doing the heavy lifting to be responsible for producing great docs, just adequate ones. For one, they don't need it. Open Source is all about Selfishness, anyone that says its about Altruism or Grand Visions hasn't been in the trenches long enough. On the pragmatic side, the guys who can fix bugs in perl are scarce and are best left to doing what they do best. Finally, I don't think you can produce great docs by bits and pieces. It requires always keeping in mind the Big Picture.
A solution is to have an editor, really a bunch of editors. Folks who just sit around fixing up the existing documentation and rewording new docs as it comes in. This could be as simple as a mailing list of folks who are decent writers and want to fix up the Perl docs. There's lots and lots of people who want to do "something for Perl" yet aren't ready to dive into p5p. Editing the docs is the perfect place for them to start. They don't even have to necessarily be experts in Perl, just able to read a paragraph and tell if its good explanatory prose or not. Or even simple things like spell and grammar checking.
Here's a simple way to solve the problem:
#3 is very important in that its #3 and not #4 or #5. Start patching *then* play around with fancy infrastructure.
#4 is important to filter out some of the noise which will be generated by the editing process before it hits the overloaded pumpking. It also allows the patches to be submitted in coherent bundles rather than dribbling in seemlingly unrelated posts.
#5 is important to building a strong base of editors who aren't necessarily all that technically savvy. People think generating and submitting a patch to p5p is a Pretty Big Deal sort of in the same way people think uploading your first module to CPAN is a Big Deal. Its not, but people think it is. So its important to make it as painless and fast as possible to go from "I'd like to edit the Perl docs some" to "here's a patch!" Think of it like organizing a work force of interns. You have no idea what their skills are. You have no idea how long they're going to be around. So its best to get them working as quickly as possible with a minimum of hassle.
Some existing things that might seem like they're a solution but aren't:
So there ya go. Its pretty simple. Like any other Open Source project it just requires someone to do a bit of Real Work to get it rolling working from the bottom-up. Maybe I'll ask Ask to setup editors@perl.org and jump start it myself.
I think the "bike shed" metaphor is a good one in this case:
you can go in to the board of directors and get approval for building a multi-million or even billion dollar atomic power plant, but if you want to build a bike shed you will be tangled up in endless discussions.
From A bike shed (any colour will do)
The docs are a good reference but probably not the best thing to learn Perl from. That's not necessarily a bad thing, nor does it make Perl unfriendly to "newbies". There's such a wealth of decent books to help out. I learnt by reading through "Learning Perl" a couple of times and kept "Programming Perl" by my side as I dived into things.
If people do need volunteers to help clean up things I'd be more than happy to help, but I feel that it would be better as a top-down project than bottom-up, splitting the documentation into managable parts etc, rather than a general call to make things better. That's just my opinion, I may be wrong.
