On 5/18/07, Marc Espie <[EMAIL PROTECTED]> wrote:
If I start with the DBIx::Class manpage, I will see a generic synopsis, and then tendrils all over the place to all kinds of pages, which (more or less) all mix reference documentation, examples, AND tendrils to other stuff like C3::Class or SQL::Abstract. If you haven't worked with any of this stuff, even if you know basic perl really good, it's a bit hard to `jump in'. I believe that the documentation could be improved by being a bit more segregated, with reference on one side, and examples on the other.
My opinion on how to segregate things and get new people pointed at the right stuff (which I think is what we're already tracking towards naturally, but perhaps we need some directed effort): 1) The pod in the class files (DBIx::Class::Resultset, etc) should be pure reference information, with an entry per method/accessor describing details about documented behavior, return types, arguments, etc. This is pretty much already the case in most places. 2) The main "DBIx::Class" pod should probably start off very near the top with a pointer to DBIx::Class::Manual, and point out that the class docs are reference material, and new users should start with the Manual. 3) From there, perhaps we need to refactor DBIx::Class::Manual and its subdocuments to be more new-user friendly if it isn't enough already. Any suggestions or patches on that front welcome. -- Brandon _______________________________________________ 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/ Searchable Archive: http://www.mail-archive.com/[email protected]/
