[plt-scheme] Tables in Scribblings

I would disagree that most people are lazy readers in this case.  I
personally have skimmed the entire Scribble manual and read the @-reader
part in detail and I couldn't figure it out.  The same with tables.  It
certainly isn't obvious that the only way to actually make a table is to
literally call make-table with all of its vagaries and getting exactly the
right (listof (listof ...)) figured out without an example.  [And, the
examples we do find are often obscured behind a level of abstraction that we
in turn have to figure out.  It might be good coding, but not so good as an
example.]

I also know that things take time and I'm sure we'll have a Scribble Guide
and better examples over time.  And, I do appreciate the quick responses I
tend to get on the list.

There are many of us with PLaneT packages who are trying to catch up with
Version 4.0.  I'm pretty much there except for the documentation and it has
been rough going for complex collections.  I think the thing that would have
helped the most is for someone to show us a canonical PLaneT package, with
documentation, that you guys have looked over and said, "Yes, that's the
right way to do it."

Doug

P.S.  Please understand that all of this is indended as constructive
criticism.  We're all trying to improve the tools we have/provide.

On Thu, Sep 11, 2008 at 7:22 PM, Eli Barzilay <eli at barzilay.org> wrote:

> On Sep 11, Jay McCarthy wrote:
> > On Thu, Sep 11, 2008 at 7:08 PM, Eli Barzilay <eli at barzilay.org> wrote:
> > > There's this example, which is pretty explicit:
> > >
> > >  @foo{The prefix: @"@".}     reads as  (foo "The prefix: @.")
> >
> > Now that you show them, these should have helped me a lot. But as I
> > read through I saw @foo and said, "But I'm not writing a call or
> > something inside a call, ignore it." If I were an extreme reader, I
> > should have noticed. But I'm lazy documentation reader and didn't
> > see it. (In fact, I'm sure its been there the last 6 or 7 times I've
> > tried to remember this and I've missed it every time.)
>
> (Yes it has, the whole thing didn't change much since it was in
> doc.txt form.  But the fact that you missed it so many times is what
> makes me think that there's a problem in the current organization of
> the text.)
>
> > Clearly something is wrong, but it's probably me. Forgive my honesty
> > :)
>
> Well, I think that most people are lazy readers when it comes to
> reference manuals.  You want to get to the point that gives you what
> you want.  Since the reader chapter reads almost like a story with
> lots of examples, I think that a simpler "quick intro" paragraph will
> be a good thing.
>
> --
>          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
>                  http://www.barzilay.org/                 Maze is Life!
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20080911/886cea06/attachment.html>