Revising READMEs

Internals
1

I'm planning to revise READMEs of many repos under the Racket organization (Racket · GitHub). The goal is to make it easier for people to understand what the repo is about. It would be nice to get a brainstorm on what to do.

Take GitHub - racket/2d: 2d syntax as an example.

Here are my intended changes:

  • Add a few sentences to describe what the packages in the repo are implementing
  • Link to the documentation page
  • General cleanup (fix typos, etc.)

Following is what I am unsure about:

Contribute to Racket by submitting a pull request, reporting an issue, joining the development mailing list, or visiting the IRC or Slack channels.

  1. Since this README was written, Discord becomes much more active than Slack (and IRC?). I don't think adding Discord (or replacing Slack with Discord) is a good idea though. It would be better if we don't mention any specific social platform at all, but instead link to a central page that contains the information. This makes it easy to maintain and keep it up-to-date.

    Do we have this "central page" already?

  2. For "development mailing list", we should definitely link to Internals - Racket Discourse, not https://lists.racket-lang.org/. But should https://lists.racket-lang.org/ also be modified to let visitors know that they are supposed to go somewhere else?

3 Likes
2

I think we should 100% pivot to IRC.

Sorry, couldn't help myself.

  1. I think the best candidate for a central contact page here is the "community" tab of racket-lang.org. I am not aware of a way to link to this tab directly, Though I have not checked out the racket-lang-org source repo, there might very well be a URL to get to this directly.

  2. I think that lists.racket-lang.org should have a big notice at the top, suggesting that people use the other community links... which kind of falls back to #1, a URL to link to that page.

@spdegabrielle , is there a better landing page that you're aware of here?

3

Should also have said: many thanks for tackling this!

4

The list page is different https://lists.racket-lang.org it should direct people to https://racket.discourse.group/ and note that is can be used as a web forum or as a mailing list.

For a landing page I refer people to https://racket-lang.org but I’d prefer community to have its own page and a big link on the home page so it is easily linkable.

See my finely crafted mockup;

IMG_6674
IMG_66741125×2436 244 KB

  • I don't believe it is possible to direct link to the Community tab under the Ecosystem section

This is the pollen code: https://github.com/racket/racket-lang-org/blob/a85e3ba4947314919adccdd704e36e46ae654267/www/index.html.pm#L357

...

PS: Hilariously the Racket users google group description refers to a community page that no longer exists:

The Racket programming language users mailing list. See http://racket-lang.org/community.html for details.

Since it is possible that people will find the google group without going to https://lists.racket-lang.org I've now changed the group information:

image
image1552×432 47.9 KB

and the about page:

image
image1292×476 44 KB

It would be good to do the same for 'announce' and 'dev' Google groups linked from https://lists.racket-lang.org, but I lack the permissions to do it myself.

...

PPS Not hilarious - over 600 pending members for https://groups.google.com/g/racket-users as recent as this month.
I am taking the following action

  1. approving all
  2. sending an apology message with instructions to join https://racket.discourse.group/
  3. trying to work out how they came to be 'pending'

best
Stephen

1 Like
5

never mind - they are pending invitations from 2015 that were never taken up
there is only a few dozen membership requests.

confusing ui.

s.,

1 Like