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.
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:
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!