<div dir="ltr"><div><div>I've been learning Scribble so that I can document a small 
library. I think that some sort of users guide 
specifically for documenting libraries that <i>hides </i>details would be very useful. I found myself reading quite a bit of 
prose and only having a vague sense of how to do things. Now when I
 go back through the docs (second or third time), they make more sense. 
So they seem to be a good reference, but they were fairly difficult the 
first time through.<br>

<br></div><div>Some things that might be useful in such a guide:<br></div><div>- Condensed version of sections 1.1-1.7<br></div><div>- Larger examples<br>    + Being able to view source and rendered versions?<br></div><div>


    + Idioms. I don't really get a sense of the idiomatic usage for documenting libraries<br></div><div>- Condensed version of section 4<br><br></div><div>Pointer chasing also seemed to hinder my efforts. Take for example <a href="http://docs.racket-lang.org/scribble/eval.html" target="_blank">http://docs.racket-lang.org/scribble/eval.html</a>.
 `interaction` (the first documented form on the page) has a description
 "like `racketinput`, except...". Following the `racketinput` link 
brings me to documentation "like `racketblock` ...". Following the 
`racketblock` link brings me to the documentation that I was looking 
for. But then I get down to rest of the forms on the eval page and 
get really lost. Perhaps `deftogether` could help here.<br>
</div><div><br></div><div>I apologize for the above criticism not being very constructive. I'm still trying to understand the difficulties I had in learning Scribble (for a particular purpose), and the ways in which it could have been easier to learn.<br>

</div></div><div><br></div><div>Thanks for reading,<br></div><div>Josh<br></div></div>