> Introductory documentation is Sequel's weakest area, IMO. The RDoc
> documentation is fairly comprehensive, but admittedly terse in a lot
> of areas.
>
> I agree.
> Unfortunately, people are not specific when they ask for introductory
> documentation, and not being a beginner, I'm not sure what the basic
> stumbling blocks for new users are. If you could give a rough outline
> of the documentation you'd like to see, I could probably work on it.
>
> Nuances of the library are what falls through the terse/dense documentation
we have now. I've been heavily using Sequel for about 18 months now and my
understanding of both Ruby and Sequel has grown exponentially in that time.
Believe it or not, Sequel has taught me a lot of Ruby. The following are
just some memorable events along my way to mastering Sequel.
One of the biggest mistakes I've made is calling update dataset before
adding a filter call.
That is,
DB[:patients].update(:code => 5).filter(:chart => 1234)
is not the same as:
DB[:patients].filter(:chart => 1234).update(:code => 5)
The select construct is so easy to mix up the order of things, its not too
hard to imagine a beginner not knowing the real rules to ordering of various
calls and their ramification. Covering how to correctly construct these
calls and what the ramifications are would help the beginner that is
starting to grok sequel along a little better.
Better coverage of the fact that as you chain each dataset method calls,
you're getting back a cloned dataset (recent sequel-talk thread) so that
each is always mutable. I never quite realized this was happening, but now
that I know, it helps me understand how Sequel works a lot better.
Expanding explanation of what's going on with Virtual Rows. Better "common
usage" examples of the virtual rows that isn't all packed into one table.
That last one actually brings up an idea....what about some documentation
that takes a tutorial approach to demonstrating Sequel's usage.
One other thing, although there's lots of documentation on the main site,
going from one theme to another is disorienting. So finding a way to make
generated rdocs, and hand-written docs a bit more alike would help a lot.
If the hand-written docs had hrefs back to the rdocs (or vice versa) to aid
jumping to/from pages/sections, that would be very beneficial to exploring
the docs more. When I get lost in the docs, I drop back to Google and hunt
for stuff rather than staying within the documentation pages and trying to
click the many auto-generated links.
Michael
--
http://codeconnoisseur.org
--
You received this message because you are subscribed to the Google Groups
"sequel-talk" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sequel-talk?hl=en.
