On 3/29/06, Matt S Trout <[EMAIL PROTECTED]> 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 _______________________________________________ List: http://lists.rawmode.org/cgi-bin/mailman/listinfo/dbix-class Wiki: http://dbix-class.shadowcatsystems.co.uk/ IRC: irc.perl.org#dbix-class SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/
