On Nov 21, 2019, at 6:27 PM, Alexis King wrote: >> 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.
It is definitely true that poor documentation is a general problem with programming languages and the Racket Guide and Racket Reference are, indeed, among the best that I have seen. I really like the fact that the Racket community explicitly recognizes the need to have both a guide and a reference. Documentation actually is a big problem almost everywhere these days. > > 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. A lot of what I have been working on in Racket is GUI related. That might be part of the reason my experience has been so different than yours. I have almost entirely been using the Racket Guide rather than the Racket Reference. I suppose I should start collecting examples of lack of examples. As it happens, my next project is about creating stand-alone executables. Look at the Racket Guide about raco distribute and there are no examples at all. I'm looking here: https://docs.racket-lang.org/raco/exe.html?q=raco%20distribute I also have not been able to find Racket examples very easily with a web search. I did some example searches just now to make sure I'm right about that and it looks like my default search engine, DuckDuckGo, has a particular problem with Racket. DuckDuckGo, usually gets just as good, and sometimes better, results than Google, in my general experience. However, I got better results with Startpage for a few Racket related searches. For example, I recently needed to use a PBKDF in my Racket code. Search for "racket pbkdf" (without the quotes) in DuckDuckGo and you don't get much of use but Google or Startpage get you straight to the most relevant material. So I'll have to make sure to try Startpage for my Racket work from now on. Maybe this part is not so bad as I thought. Something else which I am not able to find easily about creating standalone executables is an overall description of how to do this. If I understand correctly, there are at least three methods. There are command line tools, there is the "Create Executable" command in DrRacket or you can create and run a makefile. Are there limitations to any of these compared to the others? The documentation probably belongs here: https://docs.racket-lang.org/guide/exe.html I do expect that this blog post will be helpful: https://www.greghendershott.com/2017/04/racket-makefiles.html I'm sure that I can also find lots of examples of makefiles around which I can look through but it is nicer to have some official documentation. I probably will create some documentation about this myself but I would want to run it by someone with more knowledge on the topic before contributing it to the official documentation. It's easier to create a blog post and give the information on a this-worked-for-me basis. What I would go ahead and add to the official documentation is a link to the DrRacket Create Executable documentation, which is missing at first link above. > 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. The part about making contributions is one thing. The other is that it definitely has been my impression that I have frequently gone through pages in The Guide and still not known where to start. That leads me to think that there needs to be more of a culture of creating examples directly in The Guide. Perhaps, like my example about creating executables, there are other cases where the documentation about all the individual functions are there but something al level up, about the overall process, is missing. The only other two languages which I have used much are Perl and R. Perl, at first, I learned mostly from books (mostly O'Reilly) and they have lots of good examples. Later on, I ended up mostly using Stack Overflow for figuring out how to do new things in Perl. R has especially bad official documentation, in my opinion, but some really good unofficial documentation. The official, manual page style, documentation is usually too terse to be useful. The other form of documentation, which they call "vignettes," are not written as reference material nor do they typically cover all functions of the library they are about. I learned R mostly through a combination of blog posts, kind of like the one from Greg Hendershott referenced above, and through attending seminars. After that, Stack Overflow became the primary reference material. I have found some useful stuff about Racket on Stack Overflow from some of the same people on this forum but not to the level there is with R and Perl. I suppose that goes with the popularity of the language. One thing I have learned from creating documentation myself is that it is best to do it in stages. Just get something out there first and get comments on it. I always miss things but what people miss is often not what I would have anticipated. So, I have to keep going back to the documentation and fixing it. It can be a lot of work. To rephrase what I said earlier, if there are people in the Racket community with time available, I think documentation should be a priority even though things may be worse with other languages. -- 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/F29235BF-866C-46F5-9EE8-27126193C75E%40biomantica.com.
