Marketing & CPAN – mutually exclusive?
March 15, 2010 § 1 Comment
One of the big efforts in the Perl community at the moment is to address the dreaded “m” word. No, not our mothers – marketing. For some reason, there seems to be 2 distinct camps – those who hate marketing and think it’s evil, and those who understand it’s necessity. Luckily, those in the latter camp are doing a great job of recruiting people who previously disliked this whole marketing thing. I’m blogging from bed right now as I’ve had some thoughts about marketing and the initial impression Perl gives to users.
I started off by considering some massive non-Perl projects – Ruby on Rails, Django and Pylons, to name but a few. All of these projects have their own websites with some pretty nice designs. However, when I think about Perl and the latest and greatest work, only a handful of them have sites. Catalyst has a website that hasn’t changed for years and that does little more to link to search.cpan and a few other places. Moose has a single page with far too many links on, but it’s a step the right direction. DBix::Class doesn’t have a page at all (other than CPAN), though I think it definitely should.
The big problem I have with these 2 examples though is that the are fairly hostile to a new user. I look at Django’s documentation page and it’s nicely structured into some getting started documents, then moving down into some API stuff. Ruby on Rails documentation page is a portal giving me links to guides, or API reference materials. Catalyst’s documentation link gives me… this
What the hell is this? At least, I’d initially think that as a new user. There is extremely little structure, and the only structure there is designed for the machine (Perl namespaces) rather than the reader. A documentation landing page for such an influential project should give clear structures and suck in new users so they are immediately going “Wow, that’s neat!” and of course providing easy navigation for more advanced users to find the exact API documentation they need
Away from the portal itself, I don’t think viewing documentation on CPAN is particularly pretty either. For some things it works nicely (the catalyst tutorials feel like a good start, but there’s still too much cruft at the top of pages). But it could be better – we have no syntax highlighting, we have a very top-to-bottom format (where we could benefit from sidebars) and there is very little room for some other nicities like a “Careful!” or “Pro-tip” style hint boxes
As for API documentation, I think CPAN does a mixed job, which is really a problem with POD not CPAN itself. POD is excellent because it’s so free form, and it sucks because it’s so free form. Documentation is extremely inconsistent when it comes to formatting method calls – there are a variety of different formats. Some people just use the sub name, some people write the parameters in Perl style, some people use a weird DSL that’s not really anything (yes, that’s me!).
So, where am I going with this? In conclusion I think the content that is on CPAN is mixed – but for the big projects it is significantly good. But it is not accessible. There is not enough structure to it for new people to easily orientate themselves. And as we all love CPAN, I think we immediately drop our stuff there and call it a day. The other languages who don’t have tools as big as CPAN can’t have this problem – so people go and make their own site for cool shit and they usually manage to focus on getting some WHAM in there before just plonking out API docs
And where can we go now? This one is hard to say. Search.cpan.org’s layout could do with some improvements and a bit of a refresher for one – cleaner ToCs, syntax highlighting and minor typographic tweaks could all go a long way. I think something that could be excellent is CPAN to provide a different landing page for modules – Github pages comes to mind. If users could create pages inside CPAN, we could do a lot of nice stuff like structuring the documentation better while still leveraging the powerful infrastructure that’s already in place