First, one thing I would suggest is that you can create pull requests for anything right from the GitHub UI, although that doesn't let you test them. Especially for small documentation changes where there's no chance you're breaking something, I find that to be very effective and lightweight.
Second, here's how I would go about making a documentation change to something in the "main" documentation - I go to the relevant directory (such as racket/pkgs/racket-doc/scribblings/reference). - I look at the file name of the HTML page I want to change, such as https://docs.racket-lang.org/reference/envvars.html - Edit envvars.scrbl. Sometimes the file name is less easy to find, such as https://docs.racket-lang.org/reference/Manipulating_Paths.html Then I use grep (it's in "paths.scrbl", which would be easy to see from the larger section). - Create pull request. For most other packages, I'd do the following: - `raco pkg update --clone the-pkg` - cd the-pkg # and then look around for the documentation - Other steps as above. Sam On Thu, Dec 5, 2019 at 7:56 PM Matt Jadud <m...@jadud.com> wrote: > > It feels like much of the information needed to make some of the sign posts > for easy contribution are available either 1) automatically available at time > of documentation build, or 2) could be added to the info file. > > Would someone in the Racket team be able to recommend or suggest some > concrete ways the community might approach work that begins addressing the > task of making it easier to contribute to docs? > > Or, really, anyone with some insight into the tools. Some pointers would help > make it easier to contribute productively. > > Cheers, > Matt > > On Thu, Dec 5, 2019, 18:29 wanderley.guimar...@gmail.com > <wanderley.guimar...@gmail.com> wrote: >> >> 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. >> >> -- >> 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. > > -- > 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/CAAGM456FbM%2Bfbsnw-Fy6%2BWLtxDYkxD7ALNVbNCyhdvYudv4wDg%40mail.gmail.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/CAK%3DHD%2BbKJjN8bDq1BKLtCkG2FLCsc_t-oLWARUmjPF4ZZh7BqQ%40mail.gmail.com.
