For the record, my big concern with the documentation is that it's extremely hard to contribute to. I would be delighted to contribute documentation if the process was easy, but it's just not. For a language as amazing as Racket and a documentation set as high-quality as Racket's, the difficulty of helping with it is surprising.
tl;dr : Using literate programming techniques(*) for documentation is a bad idea. So is having random tiny files scattered around instead of one single .scrbl file in a location that maps to the URL of the page. (*) (i.e., having random tiny files with documentation on one particular thing and then automating the process of assembling them) My understanding is that the sequence goes like this: 1) Notice a thing you would like to change (a typo fix, add an example, etc) 1a) Ask on the mailing list how to contribute changes since the Guide / Reference / package does not have clear directions built in 2) Go to Github 3) Find which racket-related repository is the one that matters for this documentation. The Racket project itself has half a dozen repositories and it's not obvious (to me, at least) which one is which. Things on the package server will have a direct link, which helps a lot. 4) git fork the appropriate repository, git clone it to your local machine 5) grep -r through the clone to find the document that you want to modify. It will not be in a location apparent from the URL of the page you were looking at, nor will it be named what that page was named, nor will it contain all of the content from that page. Also, it will be in Scribble, which is a DSL that requires non-trivial effort to learn and is non-trivial to read. Still, it produces amazing output so that's probably worth it. It's intimidating when you're just getting started, though. 6a) make your change 6b) google for how to rebuild scribble documentation 6c) rebuild (by default this will rebuild all documentation), verify you made the change correctly 7) git commit, git push 8) go back to github and submit a pull request 9) (when (eq? (sync pr-msg-ch) 'Accepted) (exit)) 10) make requested changes 11) git commit, git push, goto 9 Compare that to what it looks like in, e.g., Perl 1) Notice a thing you would like to change (a typo fix, add an example, etc) 2) got to CPAN and search for the package / tutorial / etc. clicking on the name of the package gets you a listing of all files in the package (cf https://metacpan.org/release/ETHER/Moose-2.2012) 3) click on the 'Package::Name::Contributing' file and do what it says. This will probably be similar to the Racket workflow except that: a) The complete details are spelled out. b) There is a link directly to the repository c) The location of the file you need to edit is obvious from the URL of the documentation page that you're changing d) The file contains the complete text of the page so it's easier to find and easier to verify that your edits were correct e) The file is in POD, which is so simple that you can generally learn what you need just from glancing at the file, and it's easier to read than Scribble. It's simple enough that you generally don't need to rebuild it to HTML, but if you choose to then you can easily rebuild just that page. Example of a Contributing file: https://metacpan.org/pod/release/ETHER/Moose-2.2012/lib/Moose/Manual/Contributing.pod (NB: All major Perl packages have a Contributing file and the 'create a package' tool for generating Perl modules creates a stub version for you so it's hard to forget. If the author somehow *does* forget and the package doesn't have its own Contributing file then CPAN will show you a default version that contains all critical information. Also, it's easy to find the Contributing file: Go to the package listing that's available directly on CPAN and Ctrl+F for "Contributing") On Tue, Dec 3, 2019 at 5:26 PM James Platt <j...@biomantica.com> wrote: > > On Nov 25, 2019, at 1:29 PM, Stephen De Gabrielle wrote: > > > Many packages contain an /examples folder, and adding examples is an > easy way to contribute. > > I did not know that. So, I guess the strategy is to find the git > repository for the package and look there? In any case, I haven't been > finding these examples with a general web search. > > > > > There is also https://github.com/racket/racket/wiki/Artifacts > > > >> This page captures useful code snippets that are too small to be a > package. > >> > >> Please contribute your own! > > > > Though these might be better places in documentation, or in /examples > > That artifacts wiki a good thing to know about. Most of these are a > little more complex than I am thinking are good for documentation but I may > well contribute some small but useful code. I sometimes create my own > examples as I go because I often look back through my own code to refresh > my memory on how to do something. > > -- > 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/D5A56D93-963F-412D-9CA6-7DE3A17F6148%40biomantica.com > . > -- 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/CAE8gKodBn9oA_FHsbAbpMcvEUu37YoX7KpqStM9ZXsaAYKfyMw%40mail.gmail.com.
