> On Nov 21, 2019, at 11:21, James Platt <j...@biomantica.com> wrote: > > If we can direct more of the energy of this community into, not just > improving the documentation, but the way we do documentation, it would be a > major improvement. Requiring lots of parentheses doesn't bother me. Lack of > infix notation doesn't bother me. Lack of documentation does.
Every so often I see this sentiment expressed, and I’ll be entirely honest: I find it very surprising! I don’t at all want to suggest your experiences are untrue, or that they’re somehow your fault or not worth fixing, but they’re so contrary to my own that I must be missing something. I would go so far as to say that my experience with Racket’s documentation is far and away the best of every programming language I have ever used, even without adjusting for its comparatively small community. I will concede that racket/draw and racket/gui are particularly sparse in the way of inline examples—perhaps something about the amount of context setup often necessary—but as the main distribution goes, that feels more like an exception than the norm! If you pick any section in the Datatypes chapter of the Racket Reference, for example, virtually every binding has typeset examples (using the scribble/example library you mention). Sections with fewer inline examples usually at least have links to example-heavy companion sections in the Guide. Even a library like pict, which is visual in the same way racket/draw and racket/gui are, has typeset examples for nearly every documented export. I agree that it would be nice to make contributing small documentation improvements more accessible, but your wording seems to suggest you feel there is a deeper, systemic problem with the existing documentation. Could you say more on what that is? Or, maybe better yet, could you point to some other language’s documentation that you feel does things better that we might take inspiration from? I, at least, would find that extremely helpful to understand what steps Racket could take to do better. -- You received this message because you are subscribed to the Google Groups "Racket Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/12BB5A99-B6AD-4474-AFC8-4AA66D47E52E%40gmail.com.
