use Perl

[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:

1. Create a mailing list. Call it editors@perl.org. Doesn't really matter.
2. Get interested leaders together on the list. Kake, Casey West, Ziggy off the top of my head. Current pumpkings should probably join, too, so they can see patches.
3. Start editing and patching.
4. Declare a seperate doc pumpking to filter the doc patches and check for basic technical accuracy. This just takes some load off Jarkko and Hugo in case the editors produce a lot of noise.
5. Create a simple infrastructure for editing and submitting patches for the bleading edge documentation without having to download bleadperl and play with patch. This might take the form of a cunningly designed Wiki.

#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:

• pod-people@perl.org This is really more for discussing POD and POD tools than discussing the docs.
• Perl Documentation Project This appears to be stillborn, yet salvagable. :(
• learn.perl.org This appears to be more about feeding docs to beginners, less about producing those docs. Editors will likely come from the folks who answer lots of questions on the beginners lists.

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.