I’ve been spending a fair bit of time working on Perl 5 core documentation. I started by editing and reorganizing some of the documents related to core hacking. This update will be in 5.14, due to be released in April. I’m also working on replacing the existing OO tutorials and updating the OO reference docs, though this won’t make it into the 5.14 release.
There’s been a lot of discussion on my OO doc changes, some of it useful, some of it useless, and some of it very rude (welcome to p5p!). Many of the people in the discussion don’t have a clear vision of who the docs are for. Without that vision, it’s really not possible to say whether a particular piece of documentation is good or not. A piece of documentation has to be good for a particular audience.
There’s a number of audiences for the Perl 5 core docs, and they fall along several axes. Here are the axes I’ve identified.
Newbies vs experienced users
Newbie-ness is about being new to a particular concept. You could be an experienced Perl user and still be new to OO programming in general, or new to OO in Perl.
For my OO docs, I’m writing for two audiences. First, I’m writing for people who are learning OO. That’s why the document starts with a general introduction to OO concepts. Second, I’m writing for people who want to learn more about how to do OO in Perl 5. For those people, the tutorial points them at several good OO systems on CPAN.
I’m not writing for people who already know Perl 5 OO and want to learn more, that’s what the perlobj document is for.
How the reader uses Perl
Perl is used for lots of different tasks, including sysadmin scripts, glue code in a mostly non-Perl environment, full app development, etc.
Ideally, we’d have tutorial documents that are appropriate for each of these areas. I think the OO tutorial is most likely to be of interest to people writing full Perl applications. If you’re just whipping up some glue code, OO is probably overkill.
It would also be great to see some job-focused tutorials, like “Basic Perl Concepts for Sysadmins” or “Intro to Web Dev in Perl 5”. Yes, I know there are books on these topics, but having at least some pointers to modules/books/websites in the core docs is useful.
Constraints on the reader’s coding
If you’re doing green field development, you have the luxury of using the latest and greatest stuff on CPAN. If you’re maintaining a 10-year old Perl web app (I’m so sorry), then you probably don’t. Some readers may not be able to install CPAN modules. Some readers are stuck with in house web frameworks.
People stuck with old code need good reference docs that explain all the weird shit they come across. People writing new code should be guided to modern best practices. They don’t need to know that you can implement Perl 5 OO by hand using array references, ties, and lvalue methods
My OO tutorial is obviously aimed toward the green field developers. It’s all about pointing them at good options on CPAN. As I revise perlobj, I’m trying to make sure that I cover every nook and cranny so that the poor developer stuck with 2001 Perl OO code can understand what they’re maintaining.
(Sadly, that’s probably my code they’re stuck with.)
I’d like to see more explicit discussion of who the intended readers are when we discuss core documentation. Any major doc revision should start with a vision of who the docs are for.
There’s probably other axes we can think about when writing documentation as well. Comments on this are most welcome.