<div dir="ltr">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.]<br>
<br>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.<br><br>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."<br>
<br>Doug<br><br>P.S. Please understand that all of this is indended as constructive criticism. We're all trying to improve the tools we have/provide.<br><br><div class="gmail_quote">On Thu, Sep 11, 2008 at 7:22 PM, Eli Barzilay <span dir="ltr"><<a href="mailto:eli@barzilay.org">eli@barzilay.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="Ih2E3d">On Sep 11, Jay McCarthy wrote:<br>
</div><div class="Ih2E3d">> On Thu, Sep 11, 2008 at 7:08 PM, Eli Barzilay <<a href="mailto:eli@barzilay.org">eli@barzilay.org</a>> wrote:<br>
</div><div class="Ih2E3d">> > There's this example, which is pretty explicit:<br>
> ><br>
> > @foo{The prefix: @"@".} reads as (foo "The prefix: @.")<br>
><br>
> Now that you show them, these should have helped me a lot. But as I<br>
> read through I saw @foo and said, "But I'm not writing a call or<br>
> something inside a call, ignore it." If I were an extreme reader, I<br>
> should have noticed. But I'm lazy documentation reader and didn't<br>
> see it. (In fact, I'm sure its been there the last 6 or 7 times I've<br>
> tried to remember this and I've missed it every time.)<br>
<br>
</div>(Yes it has, the whole thing didn't change much since it was in<br>
doc.txt form. But the fact that you missed it so many times is what<br>
makes me think that there's a problem in the current organization of<br>
the text.)<br>
<div class="Ih2E3d"><br>
> Clearly something is wrong, but it's probably me. Forgive my honesty<br>
> :)<br>
<br>
</div>Well, I think that most people are lazy readers when it comes to<br>
reference manuals. You want to get to the point that gives you what<br>
you want. Since the reader chapter reads almost like a story with<br>
lots of examples, I think that a simpler "quick intro" paragraph will<br>
be a good thing.<br>
<div><div></div><div class="Wj3C7c"><br>
--<br>
((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay:<br>
<a href="http://www.barzilay.org/" target="_blank">http://www.barzilay.org/</a> Maze is Life!<br>
</div></div></blockquote></div><br></div>