I think your point is totally valid, and I feel that I already saw such discussion in the mail list.
You can simplify the process by searching a piece of the documentation in github. For example, I search for a piece of the docs from rackjure (1) which is the second result in my search. (1) https://github.com/search?l=&q=macro+automatically+adds+the+parentheses+language%3ARacket&type=Code On Thu, Dec 5, 2019 at 12:27 PM David Storrs <david.sto...@gmail.com> wrote: > 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 > <https://groups.google.com/d/msgid/racket-users/CAE8gKodBn9oA_FHsbAbpMcvEUu37YoX7KpqStM9ZXsaAYKfyMw%40mail.gmail.com?utm_medium=email&utm_source=footer> > . > -- Abraço, Wanderley Guimarães -- 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/CAAmHZoe73tMi%3Deh61O14qhfHAcpGu7%3DXkB6gcx5Fuk0FWApq%3Dw%40mail.gmail.com.
