Recent Python experience that might inform Racket docs...
I'm recently dusting off my Python skills[1], while switching to Python 3, so I'm checking documentation for every little thing.
It was a little surprising to me, that the current official Language and Standard Library references did not seem very intuitive, compared to those of Racket. The short version is that some of the fragmenting of topics seemed unnecessary, and particularly disruptive (e.g., documentation would just end before talking about something that had to be there, so you'd confirm that you were in the most plausible manual and section, then you'd go and start opening links from what you just read in tabs).[2]
To try to inform Racket docs from this inspiration/itch, I'm aware that there's very limited resources, but, when possible, I'd like to suggest:
* As I've mentioned before, I think it would be good if the Reference and Guide were consolidated. I still find the distinction between the two counterproductive, when I go to read up on something, and need to keep checking that I'm not missing half of the key information, including what I need. I think this part of the core is a closed world, and small enough, for one manual, and I don't understand the schism.
* Consider which of the separate core manuals should be incorporated into the main manual, rather than buried somewhere in the huge "wall of manuals" list on the documentation page, possibly only discovered through haphazard search. Especially if they're key/central. (Or, alternatively, break up everything, so at least it's more consistent, and we always go to the wall of manuals list for any topic. But semi-random fragmentation of now-central core stuff due to evolution or historical accident would seem to cost us every time someone needs that information.)
* Going forward, with new core documentation being written, try to put it in the best place for discovery and core-ness in context (perhaps inline as a section of topical material in core manual, or maybe it's a chapter of the core manual, or maybe it's a big thing that's part of core but really a fringe topic that should be its own doc, or maybe it's not core).
* Tutorials... The main core manual can have tutorial-like discussions like the current Guide does, in with the topics. We also want to encourage tutorials that are purely redundant with the core manuals in the core-specific information they contain, and these can be separate and developed in a very distributed community way. (And, in the development of each tutorial, maybe there's a fuzzy sense of the distinction between "this part really belongs in the core manual -- probably lots of everyone wants to see this when they're looking at that topical chapter" and "the rest of this narrative is redundant with the core manual, primarily an alternative pedagogic approach for a particular audience or side topic, and should be an independent tutorial"). I'll group "cheat sheet for moving from language X to Racket" in with tutorials, and suggest that they should also be redundant with the core manuals in the core-specific info they contain.
* I'd lean towards putting noteworthy performance notes inline with the respective topics. For example, the contiguous sections that contain all documentation about hashes (the keyed collection kind) also characterize the performance, and might link to alternatives in this discussion. And maybe so very briefly mention that these are used similar to particular abstractions in super-popular languages. I appreciate one reason not to mention performance in the text that a new Racketeer will be looking at is pedagogic (people get tripped-up overthinking performance before they've learned basics and idioms), but I think we can say a hash get is O(whatever) without crippling newbies with analysis paralysis. However, broader performance optimization strategies and tools not specific to, say, hashes, would be its own chapter, of course. (If someone developed a rigorous cost model, even that (the eventual Racket engineering documentation, not any separate academic paper, nor any tool support) might be inline with the canonical topical text, rather than its own separate chapter or manual; I'm not sure.)
Again, resources are tight, and, if a lot of this is not possible even if you agree with it, then maybe just consider some gist of these suggestions when further work is happening anyway?
[1] Doing Python even for things for which Racket would work even better, partly for technical pragmatic reasons (learning ML tools that use it for examples, and for a little server tool with minimal dependencies), and partly because I briefly considered playing along with FAANG hazing of principal&senior-level engineer applicants. ("For the first new-college-grad step, I need to see whether you can code." "Uh, you have my resume, and I know you guys have heard of open source. Is this inflexibility, or institutionalized negging?" "You're pretty; you shouldn't be self-conscious about that facial birthmark I notice." "I'm sure we have collegial mutual respect, and aligned goals to find the right match, so perhaps we could focus on--" "Dance for my amusement, worm!" :)
[2] I'm not talking about OO class library doc organization, which javadoc quickly taught everyone to navigate, if we hadn't learned it from Smalltalk browsers or C++ library docs already. javadoc was imperfect, but I don't recall as much *additional* fragmentation of core documentation then as I'm seeing in some places now.
-- 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. For more options, visit https://groups.google.com/d/optout.
