[Dbix-class] RFC: Documentation/manual improvements

[hkclark at gmail.com]

On 3/29/06, Matt S Trout <dbix-class at trout.me.uk> wrote:
> Comments here -
> and if you're a relatively new user *please* pitch in, even if it's just a
> couple of lines: The newer you are to the package, the better a perspective
> you'll have on where the introduction/explanation stuff falls down.
>

Hi Matt,

First, I really like the docu improvements in 0.06.  Many thanks to
you and everyone that worked on it.

Other than the Catalyst "overlapping model name" issue we discuss
(which obviously isn't a problem with DBIx::Class), I have been
finding that I'm getting stuff to work with DBIx::Class pretty
quickly.

So, given that you have done a great job, I don't have a ton of
suggestions, but, I think some things that might help are:

* Have a "home page" type of thing that links to every other perldoc
page could be cool.  You can kinda get something like that with
  http://cpan.uwinnipeg.ca/search?query=DBIx%3A%3AClass&mode=dist
but the Kobes search engine doesn't show some of them for some reason
(e.g., the all-important "DBIx::Class::Manual").  I have found I can
pretty much just bookmark "DBIx::Class" and then use it to link to
what I want (you all have done a great job hyperlinking between
pages), but, that said, I think having a list of every pod page (maybe
grouped by subject area -- or two, one by subject area and the other
alphabetical) could help people get the "big picture" early on.

* As many examples as possible.  "DBIx::Class::Manual::Example" is
great, but I think even more could be of help to new users.

* Have a "progression" of examples where there are some really simple
ones that then lead to more complex ones (with lots of search and
attribute options used and stuff).

* I think the "mucho comments" in examples approach can help new
users.  IOW, comment on what every line is trying to do... I know it
seems like total overkill for experienced users, but new people love
that kind of thing.

* I always like examples where I can download a tarball (or cut &
paste from a script if it's a pretty simple example) and play with
things under the debugger... I'm not sure if other would find that
helpful or not.

* And, of course, if you really want to get THE BUZZ going, you need
Quicktime movies of you doing cool, sexy & amazing things (nothing to
do with your personal life here... I'm just talking about
DBIx::Class!). :-)  I know movies like the now-famous RoR movies are
big on "eye candy" and experienced folks tend to "look down" on
them... but let's face it... it can get people excited in a hurry.

Just my $.02