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!

About these ads

Tagged:

§ 7 Responses to Marketing & CPAN – follow up and an example of changes

  • kixx says:

    Try the #catalyst channel on irc.perl.org

    • acidcycles says:

      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!

      • perigrin says:

        I’m working on something for Moose specifically because of your recent posts. I hope to be able to announce something early April.

      • acidcycles says:

        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.

  • lupin says:

    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.

    • acidcycles says:

      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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

What’s this?

You are currently reading Marketing & CPAN – follow up and an example of changes at Cycles.

meta

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: