Slash Boxes
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

schwern (1528)

  (email not shown publicly)
AOL IM: MichaelSchwern (Add Buddy, Send Message)

Schwern can destroy CPAN at his whim.

Journal of schwern (1528)

Friday April 18, 2003
06:57 AM

How To Get Better Perl Docs

[ #11720 ]

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

  • This is really more for discussing POD and POD tools than discussing the docs.
  • Perl Documentation Project This appears to be stillborn, yet salvagable. :(
  • 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 and jump start it myself.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
More | Login | Reply
Loading... please wait.
  • by cwest (1514) on 2003.04.18 9:17 (#19267) Homepage Journal
    We are in the process of ramping ourselves up. We're going to be doing edtorial work for the Perl FAQ, and one of the goals of the project originally was to do editorial work for the core Perl documentation as well. We are the folks you're looking for.
    Casey West
  • I'd like to point out as well that the perlfaq*.pod manpages have their own CVS repository and mailing list(s) : perlfaq-workers [] and perl-documentation []. I still don't get the difference between the two, even if I'm officially in charge of integrating the FAQ changes into Perforce.
  • bike shed (Score:2, Interesting)

    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