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
____________________ Racket Users list: http://lists.racket-lang.org/users