[Dbix-class] some suggestions about the DBIx::Class documentation

[Brandon Black]

On 5/18/07, Marc Espie <espie at nerim.net> 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