Enlightening perl's documentation (you too can help!)
Enlightened perl programmers often complain about how outdated most online perl manuals. Truth is, some of the official documentation is quite outdated too. Perl ships with a lot of documentation, some of it is old and badly needing some maintenance.
For example, a quick ack through the documentation showed about 250 cases of open used with a glob as its first argument (e.g. open FOO;), even one in perlstyle! I think everyone agrees that in 2010 that's no longer a good example. I don't think it has a place outside of perlfunc and perlopentut. The same argument goes for two argument open and use vars. I'm sure there are plenty of other issues that I can't think of right now.
That's not hard to fix, in fact you could almost write a program for it. It may be a lot of work though to fix all of them, but not so much to fix them one by one.
Some things are harder. Some things are a lot more work. Let's take some docs on object oriented programming perlbot, perltoot and perltooc for example haven't seen major updates since 1995, 1997 and 1999 respectively. perlboot and perlobj seem to have had the most loving the past decade, but can still use some more attention. Surely we all agree a lot has happened in object oriented perl in the mean time. We don't directly assign to @ISA anymore in our modules, do we?
But there's much more to improve in the documentations.
- Why does perltrap list traps for perl4, awk and sed but not for modern languages like python, php or ruby?
- Why doesn't perlipc use IO::* instead of low level functions?
- Why isn't perlmodinstall Build.PL aware?
I suspect many other pieces of documentation that I haven't taken a good look at that could also use a spring (autumn for inhabitants of the southern hemisphere) cleaning.
The good part of the story? You can help. This work can be done not only incrementally, but also distributed.
Edited to add: So how to get started? perlrepository has detailed information how to submit patches. The easiest way is to fork perl at github and when you're done mail the perl-5-porters about it.
"250 cases of open used with a glob as its first argument" sounds like 250 cases of working code to me. People wanting to contribute to Perl might do better typing "perldoc perltodo".
Not everyone wanting to contribute to Perl has the coding knowledge necessary to work on the tasks spelled out in perltodo.
Far better to encourage those who do want to help to contribute how they can, rather than piss on projects you personally don't feel are worthy.
My "personal feelings" are that every second spent swapping syntax in the documentation is a second wasted. However else people spend their time, they will be spending it better.
Hi Leon,
I think it's a great idea to make the documentation more 'modern' - teaching newbies best practices from the start will benefit everyone.
You might want to add to your post where people should go to help.
My "personal feelings" are that every second spent swapping syntax in the documentation is a second wasted.
How kind of you to tell everyone where their skills are best spent. Please consider that not everyone may be as awesome as clearly are, or awesome in the same ways.
For those who don't have the coding chops to deal with those projects that you deem worthwhile, modernizing the Perl docs to take advantage of the features that are clearly better than the old crufty way is a fantastic way to contribute to Perl 5.
It's also possible that people might be looking for ways to contribute that aren't so time-consuming. Doc fixes are less time-intensive, yet still important.
@educated_foo: I don't think 'working' is good enough for documentation. Documentation needs to show its readers not just a working method, but also a good method. One that will produce more maintainable and less buggy code. I think that's something worth striving for by itself.
Also, perltodo shows exactly this bias. The only entry in it on documentation is one to write a new piece of it. I'm certainly in favor of an XS cookbook (I might even end up writing it), that doesn't make maintenance on older documentation any less necessary.
Another issue with perltodo is that the tasks are typically hard and/or a lot of work. There's value in small approachable tasks, in involving new people who never contributed to perl before.
@Leon: Thanks for an honest and thoughtful response. From where I sit, making documentation comply with Modern::Perl dogma looks generally useless but easy, while making Perl (a mature language) better is valuable but really hard. I would rather see people either trying the hard stuff, or making other good uses of their time.
@petdance: Unsurprisingly... not so much. My supposed awesomeness has nothing to do with this. I just don't see how getting people to change documentation to conform to someone else's coding standards is useful. They could be translating basic documentation into other languages, polishing their code for release onto CPAN, making love to their wives, or so many other useful things! Why this?
Why is it useful for the documentation to recommend using lexical variables over globals?
Why is it useful to assume that most new users of Perl 5 aren't coming from Perl 4?
Why is it useful to recommend the use of easier to use abstractions over low-level socket and IPC functions which themselves are barely wrappers over system calls?
If the answers to those questions aren't staggeringly obvious, I can see why you think all of this "Hey, Perl 5 can be a powerful, usable, robust programming language!" is merely dogmatic preferences.
Me, I think teaching novices how to avoid the hard lessons that we adepts have learned over the past decade is much, much more humane than making them suffer the same painful lessons.
It is really easy to fix all of those open() problems; it just takes work. I'll put it on my to do list though. I have been doing that already for the perlfaq, etc, when appropriate. Sometimes the docs are about using the bareword filehandle, so those have to stick around, though. :)
Some of the hardest work as a recent thread on
perl5-porters& and patches to perlfaq show isn't making the changes, it's getting them past the maintainers or an ensuing bikeshedding discussion that goes nowhere.Could a wiki work for the perl documentation?