[Dbix-class] docs updated to help dbic beginners

[Sean Davis]

On 10/13/05 3:10 PM, "Matt S Trout" <dbix-class at trout.me.uk> wrote:

> On Thu, Oct 13, 2005 at 08:32:45PM +0200, Krzysztof Krzyzaniak wrote:
>> Matt S Trout wrote:
>>> On Thu, Oct 13, 2005 at 08:09:06PM +0200, Krzysztof Krzyzaniak wrote:
>>> 
>>>> Hartmaier Alexander wrote:
>>>> 
>>>>> After talking to Matt (or should i say bombarding him with questions on
>>>>> irc *g*) we've come to the conclusion that the docs need better 'newbie
>>>>> support' (for people like me) and simply more examples as well.
>>>> 
>>>> Youre damn right!
>>> 
>>> 
>>> Yep. So, here's some things to do -
>>> 
>>> 1. There are some useful notes on the wiki. There need to be more. If
>>> anybody figures something out by asking on here or talking to the people in
>>> #dbix-class, *please* drop a quick note somewhere on the wiki.
>>> 
>>> 2. Documentation patches such as this are *very* welcome and I'll be
>>> handing
>>> out commit bits to anybody who provides a good one.
>> 
>> There is two problems, so far I can only ask the questions (and not
>> answering them) and second my english is far from perfect. So I can only
>> push the things :-)
> 
> I'm aware a fair number of people don't have the dubious privilege of
> english as a first language.
> 
> Fortunately, I'm a spelling and grammar pedant - I'll fix up submissions as
> they come in, and save my sarcasm for my fellow countrymen :)
> 
> The part I have trouble with is figuring out what people need to know and how
> to explain it to them; I write usable but extremely terse reference
> documentation but I can't write tutorial stuff to save my life.

A big step for beginners would be to have the equivalent of this page:

http://cdbi.dcmanaged.com/wiki/Beginners_guide

Noting that most of the page is code, would it be possible to simply post
the code snippets from a working app?  Adding simple headers like update,
delete, insert, search, iterator, relationships above the code chunks would
add some direction.  Alternatively, just post all the code for a small test
application (or even the test cases themselves!).  I really think that
"learn-by-example" can go a long way and save the programmer time and
documentation energy.  That said, I don't have such code yet myself (still
using CDBI), but I bet someone might.

Just my two-cents (and I am a relative beginner....)

Sean