I'm volunteering to add examples and expanded text to the Racket documentation. What would be some high-value areas to do that in? Are there particular segments of the docs that you've found hard to understand? Let me know and I'll do my best to come up with clarifications.
5 Likes
Most of my requests would be related to the scribble documentation.
Usually the examples are most helpful when scribble mixes with something else, e.g.
-
including a plot in a scribble document.
-
including code that you want to typeset only in pieces and the same code that
you want to run, e.g. when explaining an algorithm in multiple steps,
but including a consolidated "run" of the code at the end. This would
mostly revolve around the syntax for evaluators within scribble docs.
I often find myself consulting these two blog posts for bibliographies
and scribble. Making that information part of the primary documentation
could be helpful.
- Writing a paper with Scribble
- How To Use Scribble to Write your Academic Papers: A Reference Tutorial
Cheers,
"David K. Storrs via Racket Discussions"
notifications_at_racket.discoursemail.com_txnwmxfz@duck.com writes:
2 Likes
Huh, not what I was expecting. I haven't done much with complex Scribble, but I was expecting to need to learn something in order to do this, and in this case I can happily import things from those blog posts into the primary reference. Thanks for the links.
Here's what I proposed earlier in the Hackathon.
- 2htdp/image (https://github.com/racket/htdp/issues/183)
- Everything in https://docs.racket-lang.org/reference/stxtrans.html
1 Like
[humor]
Me (thinking): You know, I should give back to the community. I know, I'll volunteer to do documentation! I'm sure people would like some extra examples and doc expansion on relatively commonly-used things that could still stand a few extra details, and I've plowed through a lot of that stuff already so it shouldn't be too hard. Go me, I am halping!
Me: Hey folks, want some examples?
People: Cool, thanks. How about these things you've never touched before?
Me: Uh-oh.
[/humor]
2 Likes
No surprise. That was bound to happen. 
[me maybe adding to your horror/humor]
I think the FFI docs could use a whole lot more examples because things go boom very easily here and it's hard for a new learner to know if they got it right or wrong; until boom.
2 Likes
That is very unlikely to happen, but I appreciate your faith in me. :>