[Dbix-class] RFC: Documentation/manual improvements

[Andrew Ford]

Richard Jolly wrote:
> Nigel Metheringham wrote:
>   
>> Sent: 29 March 2006 13:39
>> To: dbix-class at lists.rawmode.org
>> Subject: Re: [Dbix-class] RFC: Documentation/manual improvements
>>
>> On Wed, 2006-03-29 at 13:13 +0100, Matt S Trout wrote:
>>     
>>> A more interesting question is - what took you a while to get your 
>>> head round conceptually, and what features did you find incredibly 
>>> useful once you were using them but hard to get up and 
>>>       
>> working in the first place?
>>
>> The biggest problem for me has been (and still is) getting a 
>> handle on how all the various classes hook together.  What I 
>> would really like is some form of diagram showing the links.
>>     
>
> A related request, perhaps. I'd really like a simple reprentation of a
> typical file/class layout. My current tree looks like:
>
> MyApp/Schema.pm
> MyApp/Schema/Foo.pm
> MyApp/Schema/*.pm           # one for each table
> MyApp/ResultSet/Foo.pm      # 
> MyApp/ResultSet/*.pm        # only for resultsets that have custom
> searches
> MyApp/Foo.pm                
> MyApp/*.pm                  # only for row objects that have custom
> methods 
>
> This seems to work. But it took me _ages_ to figure this out, and I've
> lingering doubts about whether it is correct.
>
> Secondly, the Glossary is fantastic - but needs expansion.
>   

I agree that the glossary is good.  However, I feel it is a bit of a 
minefield knowing where to start with a system as complex as DBIC, and I 
think that is almost as true for experienced perl programmers who might 
like to contribute to the project or develop components as it is for 
programmers who just want to use DBIC. 

The difficulty comes when one starts delving into the module 
documentation -- obviously one starts with the DBIx::Class, ::Schema, 
::ResultSource, ::ResultSet and ::Relationship pages, but then there is 
documentation hidden in modules like AccessorGroup, InflateColumn, PK, 
etc.  What I would like to see is an architectural overview document -- 
I just counted the '*.pm' modules in the DBIx::Class namespace on my 
checked-out subversion tree and there are 79 -- and that doesn't include 
any plugin modules.   By the time one has looked at all the modules for 
documentation and maybe printed out some of the most relevant, one does 
an "svn update" and a dozen or so modules have changed and one wonders 
whether there are any significant changes to the documentation in those 
modules.  Of course part of this is that the project is still at a 
relatively early stage in its development and I think it is great how 
the documentation is growing. 

I think the documents in DBIC::Class::Manual are a very good start at 
introductory documentation -- the documents are generally quite well 
written, well structured and don't have too much overlap.  Obviously the 
glossary needs to be expanded and I worry that the Cookbook could easily 
become a random collection of thoughts without much focus. 

I would like to contribute towards the documentation effort myself but I 
am moving from self-employment to a permanent job in just over a week 
(my first permie job in almost 20 years) and have lots of admin to get 
out of the way.  One thing that I had wondered about doing is creating a 
quick reference card for refcards.com and possibly a "pocket reference 
guide" style book (I wrote the "mod_perl Pocket Reference" a couple of 
years ago) -- though given the new job it would be a while before I 
could really devote much time to that.  Would people be interested in a 
refcard or refguide?

Regards
Andrew

-- 
Andrew Ford,  Director    Pauntley Prints / Ford & Mason Ltd            
A.Ford at ford-mason.co.uk   South Wing Compton House                      
pauntley-prints.co.uk     Compton Green, Redmarley  Tel: +44 1531 829900
ford-mason.co.uk          Gloucester GL19 3JB       Fax: +44 1531 829901
refcards.com cronolog.org Great Britain          Mobile: +44 7785 258278