Marketing & CPAN – follow up and an example of changes
March 16, 2010 § 7 Comments
If you read my last post, you will have heard me complaining about search.cpan.org’s interface about providing documentation. I argued that the quality of documentation was mixed, though the big projects (where it’s important to get as much wow factor as possible) had some great writing. However, the presentation is thoroughly lacking.
I don’t like complaining without trying to actually help, so I spent a bit of my free time today by making something that tries to incorporate the changes I mentioned.
A Catalyst documentation landing page
It’s probably lacking a little in the punch visually, but just look at that structure. As a new user I’ve got plenty of documentation about getting started – as a developer I’ve got easy access to the important APIs, and if I’m getting really geeky, there’s material for me to geek out with.
Now I should emphasize. None of this content is new – every single one of this pages mirrors something in the Catalyst::Manual. But I think that added structuring and a few explanatory paragraphs has made a world of difference. This change carries over nicely to the documentation pages themselves:
Viewing some Catalyst documentation
A readable structure, and I can jump straight into the content. If you think these arguments still hold for Catalyst, clearly you seen some of the pages…
I should stress that this is nothing more than an idea in my head at the moment. The above aren’t lockups, they are brain dumps. But I’m really keen to try and make this reality – I just don’t know enough about the Perl community to know who to talk to in order to get it done. So, if you want to talk about this – leave some comments and we’ll work something out 🙂 Even advice on who to talk too is much appreciated!
Cycles 
Try the #catalyst channel on irc.perl.org
Oh, I’m in #catalyst all the time and dropped a link there (though I didn’t get much feedback sadly) – but i’m really aiming wider than just Catalyst. Moose could benefit from this, as could DBIx::Class (and insert–name–here on CPAN).
Thanks for your comment!
I’m working on something for Moose specifically because of your recent posts. I hope to be able to announce something early April.
This is excellent! If there’s anything I can do to to help (be it typing or even just some reviewing I’m more than happy to). I’ll poke you on IRC 🙂
Yeah perl in general needs some prettying up and better docs… I think the web perldoc is actually pretty good. But the best Documentation ANYWHERE that I’ve seen is the Gentoo project and PostgreSQL. No one has better docs.
Nice work, hopefully this will be incorporated by catalyst team and the same thing will be applied to dbix-class documentaion, I guess you can drop an email to catalyst mailing list.
I think getting it into Cat could indeed be a start. As I said in above comment, I really want to see this fundamentally possible in search.cpan.org, but that’s a much bigger picture. For now if just individual projects had this, it’d be a start for sure