On Apr 14, 12:16 pm, Michael Lang <[email protected]> wrote: > > 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.
Thank you very much for providing specific examples of things that need to be improved. I'll start with your suggestions, but I encourage other people to submit specific documentation improvement suggestions. As always, I'll happily accept documentation patches too. I'll state for the record that improving Sequel's documentation is at the top of my todo list, and it's what I'll be working on for at least the near future. Jeremy -- 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.
