@kreyren Hmm, what would you consider to have exemplary documentation? Racket? I've always thought the GNU manuals were first-class.
@radehi I do like that guile can access the docs from the terminal, but the content feels like hot garbage to me i never understand anything it's trying to say
@kreyren Hmm, it sounds like you're looking for task-related context-sensitive help, rather than a manual you'd read from beginning to end. But is not clear to me how to do that for a programming language (except in the case of compiler errors, of course, but Scheme doesn't have a lot of compiler errors). Most of what is needed in programming-language documentation is "which language features or library functions do I need to write this program that I haven't written yet" rather than "how do I use library function X", isn't it?
But it sounds like Racket comes closer than Guile?
Example code is super important for programming language explanations.
@radehi all guile definitions have guile properties like 'documentation that can be used to auto-generate the context-sensitive help, but there is an issue with documenting variables that i tried to address with the devs [https://lists.gnu.org/archive/html/guile-devel/2022-11/msg00001.html]
@radehi @kreyren I'll second both opinions. GNU docs are normally pretty good and address multiple user types' needs.
Guile's manual feels like it's written with an audience of C application authors looking to add an extension language, and there's not a great "guided tour" of the ecosystem for small tasks.
Racket's docs have guided tours of the libraries (so it's easier to figure out how to do something similar to the examples _in_ racket, rather than how to add guile to something else).