[racket] Learning Scribble

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 *hides
*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.

Some things that might be useful in such a guide:
- Condensed version of sections 1.1-1.7
- Larger examples
    + Being able to view source and rendered versions?
    + Idioms. I don't really get a sense of the idiomatic usage for
documenting libraries
- Condensed version of section 4

Pointer chasing also seemed to hinder my efforts. Take for example
http://docs.racket-lang.org/scribble/eval.html. `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.

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.

Thanks for reading,
Josh
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20131121/a9c2c35e/attachment.html>