Racket glossary

General
,
1

Following up on our discussion here, I created a Github repository and would like to get some feedback.

I hope it's ok to quote the README here:

Racket Glossary

This project hopefully will result in a glossary to be included in the Racket documentation to help primarily Racket beginners and intermediate users understand Racket concepts and interactions between them.

Purpose

  • Give definitions of terms used in Racket and Scheme in general.

  • Help beginning and intermediate users understand terms encountered in the Racket documentation. Assume that readers are familiar with imperative programming, but not with functional programming, Scheme and Racket. Therefore, some entries may contain comparisons with related features in other programming languages.

  • Provide context. So some entries may have more content than you'd usually expect from a glossary.

Format

I'd like to see this glossary end up in the Racket documentation, so eventually it needs to be converted to Racket's documentation language Scribble. On the other hand, I think we should use a simpler format like Markdown for easier contributions until the content is good enough to be included in the Racket documentation.

Ideally, it would be great if there was a tool to convert Markdown to Scribble automatically. I haven't found one yet. The open source go-to tool for text format conversions is Pandoc, but while it supports different Markdown dialects as input formats, it currently doesn't support Scribble as output format. However, it should be possible to write a custom Pandoc writer to support Scribble as an output format. That's something for a different project though. :wink:

Contributions

At the moment, the file glossary.md contains only a list of terms to be included in the glossary.

My current plan to build the glossary is:

  1. Get feedback on the selection of the terms. For example, is something missing?
  2. Convert the terms to headings and add some of my thoughts as stubs to build upon.
  3. Wait for contributors to offer pull requests. :slight_smile:

I suggest doing step 1 on the Racket Discourse instance.

License

See the file LICENSE.

Hence, according to the first step described in the README, I'd like your feedback on the terms in the glossary. :slight_smile: Of course, other feedback is welcome, too. Does this go into a direction you like?

Edit: The above is the README at the time I wrote the post. The current README is here.

7 Likes
2

I made a tiny Pull Request to the glossary, and I thought I'd share how I did it as not everyone is familiar with git, racket packages and tools like GitHub and the raco pkg commands.

I have Racket 8.5 and GitHub desktop installed

  1. I went to GitHub - sschwarzer/racket-glossary: Glossary to (hopefully) be added to the Racket documentation
  2. I clicked clone to make a clone of the repository on my hard drive (with GitHub desktop)
  3. DrRacket Help>Configure command line for Racket
  4. new terminal in the racket-glossary folder on my hard drive
  5. made my edits to the files.. (.gitignore was hard because I had to work out how to see hidden files)
  6. back to GitHub desktop
  7. realise the I needed to change .gitignore so it didn't commit the temporary files
  8. commit with a comment.
  9. GitHub desktop makes a fork on GitHub and puts my commit in the main branch
  10. click make a pull request in GitHub to send my changes to GitHub - sschwarzer/racket-glossary: Glossary to (hopefully) be added to the Racket documentation as a pull request. You can see it here

If that seems messy you are right. I did it wrong but it sort of worked out in the end.

I also forgot the bit where I went to the folder for racket-glossary on my drive and typed raco pkg install and raco pkg remove racket-glossary to install and uninstall and then switching to drracket to open the local copy of the documentation to see if my changes were working.

Now I have to wait for @sschwarzer to review and hopefully accept my changes.

If I was to do it again I would

  1. fork GitHub - sschwarzer/racket-glossary: Glossary to (hopefully) be added to the Racket documentation
  2. make a new branch 'my changes'
  3. use GitHub desktop to download the 'my changes' branch on my drive
  4. make my changes
  5. raco pkg install to check them with local documentation (DrRacket Help menu)
  6. fix any mistakes
    7 . raco pkg remove racket-glossary, raco pkg install, then check the local documentation again
  7. upload back to GitHub
  8. make the pull request.

Once we have a few more entries I'm hoping @sschwarzer will add the racket-glossary package to the Racket Package catalog so it appears in the online documentation.

bw

Stephen

3 Likes
3

Thank you for the PR!

I've never worked with a Github-specific tool, but most IDEs and git on the command line let you control what you want to include in a commit. You don't need to commit everything in one go. It's even possible to commit only a part of the changes you did in a file, but that's kind of advanced if you're new to Git.

In my opinion, with Github it's even more complicated to contribute patches than with Git alone. The whole Pull Request thing adds complexity. In the old days people just sent diffs! (Sorry for the rant. :slight_smile: ) See also What is a fork, really, and how GitHub changed its meaning .

Still, I've put the racket-glossary project on Github with the thought that most people would be more comfortable contributing via PRs (because they're used to that).

Once you have racket-glossary installed, you can run

raco setup --pkgs racket-glossary

to update the documentation.

I used to be able to open the documentation for a package with

raco doc racket-glossary

but now I see a search page that tells me racket-glossary wasn't found. Maybe it's to do with the switch from installation scope (set by myself after the installation of Racket 8.4) to user scope when I switched from Racket 8.4 to 8.5. Maybe someone has an idea what's going on here?

That said, from the repository working directory, you can open the file doc/glossary/index.html in the webbrowser, so DrRacket isn't needed. :slight_smile:

I merged your PR, but added some feedback for the next time. :slight_smile:

Yes, please always create a new branch for a PR. See also Creating a pull request - GitHub Docs .

My plan is to have the entries for the "basic" category complete (or mostly complete) and then release the glossary as a package. I think it would look quite odd if I released the package now, with almost nothing in it. If someone wants to install the package in the meantime, they can run

raco pkg install git+https://github.com/sschwarzer/racket-glossary

When I started with the glossary, I had thought of writing "normal" glossary entries, i.e. just very short definitions of some sort. But shortly after starting I decided to write a bit more per entry to provide more context (like for the entries I already wrote). That said, short entries are welcome as contributions, too, because they give me a starting point for a more detailed glossary entry.

3 Likes
4

Thank you @sschwarzer for the feedback and advice!

I’ll try do another soon and follow your instructions - I’ll let you know how I go.
Bw
Stephen

1 Like
5

I had written more, but hadn't sent it yet:

By the way, please don't call your branch name my changes. :slight_smile: First, the spaces in the name are a bit inconvenient when using the branch name on the command line. Second, use a more specific name. If two people use the same branch name, it makes it quite inconvenient to pull both these branches in a local copy of my local repository at the same time. For example, in your case, you could have called the branch let_over_lambda.

Regarding the PR process itself, I think that there's an easier way to make a pull request (if it's a simple one):

1 Like
6

Thanks for the branch naming tips - I will remember that.

:grimacing:

I don’t think we should recommend this as you are not testing prior to submitting the pull request. It is a bad habit to get into, and leaves a single point of failure for testing. If you both test a mistake is far less likely to slip by.

Guilty admission - I have done this myself. :cold_sweat: submitting small PR’s for the website because I didn’t want to learn or use #lang pollen. (Pollen is fine I just don’t have the time).

Bw
Stephen

1 Like
7

I guess we have a misunderstanding here. :slight_smile: I don't suggest this simplified approach for every project. Actually, I'd recommend it for few, at least most of the time. It depends on the context.

My reasoning is that especially for the "intermediate" and "advanced" categories I'm probably not experienced enough to know how these concepts are usually/idiomatically applied, what problems they have and what they're good at. Therefore, I want to make contributions (almost) as simple as possible, even if it means slightly more work for me.

Another important thought is that we speak about documentation changes here. Of course, a patch can break the build of the documentation, but if the patches are small, it's relatively easy to figure out what went wrong, even after the change is merged to the main branch.

On the other hand, changes to code are much more likely to break things and changes from different people are much more likely to interact, so that a problem might only be noticed a while later, maybe only after a few more PRs are merged.

Regarding testing: Even if I merge a PR, it doesn't mean that I didn't pull and test it before I accepted it. :slight_smile: (*) And if I accept a PR, it doesn't mean that I won't make changes to the commits later.

By the way, there's no contradiction between testing yourself and using the simpler contribution approach. :slight_smile: You can test your changes locally and even though something can go wrong when you copy your local changes to the web form, for simple changes it's not very likely and will be noticed soonish (for documentation).

That said, I prefer well-tested PRs and merging the actual commits you made locally, but it's not a strict requirement for simpler changes.

I think agile development makes a lot of sense. This means that if the changes get more complex and more error-prone, or if more people contribute, of course we can change the requirements for contributing then. But again, depending on the kinds of changes you can use different approaches, depending on what's practical at the time.

I hope that clarifies it a bit. I really thought about the matter before I offered you the simpler PR approach. :slight_smile:

(*) It would be nice to have an automatic build of the documentation, but as long as there are few and simple contributions, it doesn't have high priority for me. Besides, even if building the documentation succeeds without errors, it doesn't mean the documentation looks as it's supposed to look. :wink:

1 Like
8

By the way, since I do the Racket stuff in my free time, it's normal for me to work in bursts. I might work a little on some weekends, but I also may take a week off occasionally to make faster progress on a project. So even if nothing or very little happens for a few weeks, this doesn't mean the project is done for. :wink: If you have doubts at some point, just contact me and ask. :slight_smile:

1 Like
9

I've added a file glossary_notes.md for notes that aren't directly usable as glossary entries. I added some meta information on that at the beginning of the file. I guess this file should make it much easier to contribute and I can imagine the information ending up there could help a lot. :slight_smile:

Note that you can also submit information that doesn't fit into a specific glossary entry (at the end of the file). For example, if you teach Racket, I'd be interested in common difficulties you see Racket students run into.

1 Like
10

I submitted a small pull request for the Currying section. Is that the sort of thing / method of sharing that you're looking for?

1 Like
11

Thanks for your PR! :heart:

I added my feedback in the PR comments.

12

You wrote that you want it to be easy for people to contribute (in the markdown thread) now in this PR your response is to point out a bunch more hoops to jump through, to change the PR to suit your taste (these additional points of "how I would like to structure this" weren't clearly pointed out before as far as I have read).

I think this seems contradictory. Personally I am not encouraged to contribute, when I feel like I am micro managed, or my contributions get a bunch of comments that seem like "arbitrary stylistic changes that are subjective and not even communicated clearly before". To be fair, I don't think that was your intent, but if I read it in isolation without taking your character into account that is how it comes across to me.

So my suggestion here would be to take a bit of inspiration from how @spdegabrielle has organized the different creative competitions and either use some form of template that allows contributors to fill in the blanks with low effort (while still giving you some of the wanted structure) or/and communicate more in an easy going manner about how contributions are added.

I think it makes sense that you have your structure and how you want to get to your goal, but it isn't necessarily easy for other people to have the same vision in mind that you do. That is why I think, you should focus on getting material through contributions, not how that material is given or structured.

Ultimately I think one or maybe a few people will be required to go over everything to bring it into a coherent structure and give it its final form, so it seems to me that transforming contributions to bullet points and later back again, may end up unnecessary busy work, that may even lose valuable information by going through multiple translations of form.

aside/disclaimer:
Maybe my view on this is a bit biased, because I had another experience (outside the racket community) where I did a bunch of work and ended up feeling like it was a waste of my time.
(Because there I felt like I am being stalled and my pr won't be accepted, just not straightforwardly declined either, which would just allow me to more easily cut my losses and accept that I would have to fork the project if I wanted to make it happen)

Not saying this is happening here, I just have a big dislike for incrementally increasing requests for "do this change", "now do this", because it reminded me of that bitter after taste, when you feel good about contributing and get met by a bunch of "not like this", "do this instead".

I think you should make it clear what are nice to haves from contributors that have the time to invest a lot of their time/focus and others that may only be able to do some drive by contributions, wanting to hand off their idea in hopes that somebody else is able to catch it and incorporate it into the finished project. That way you can get more structure from those that have the time, without missing out on good ideas.

3 Likes
13

Copying a thing I posted in the PR:

For the record, I agree with Simon Schlee here: Racket glossary - #12 by simonls To expand: what you're creating here would be better implemented as part of the Guide, not as a separate document. The value proposition of this project is that it's vastly easier to contribute to a Markdown document than a Scribble document, especially one that's spread across multiple files with unintuitive structure the way the Racket documentation is. The more demands you make on how PRs are structured, the less interest people are going to have in doing them.

2 Likes
14

Thank you @simonls and @dstorrs - it is good feedback.

I think I can safely say that all contributions are valued - even if we are not always good at expressing how much we appreciate the contributions. :star_struck:

Updating scribble or even markdown is daunting if you don’t use git and have never used GitHub. Even editing markdown files in the web ui is a confusing experience that assumes a lot of background knowledge.

I think I’ve made this mistake myself - I honestly believe that using GitHub issues for Creative Racket and Quickscript events discouraged some contributors. It is also an issue for the Plot Cookbook.

While GitHub/Git/gitlab etc. are the obvious choice for professional developer, not everyone in the Racket community is a professional developer. My experience has been that while there are a lot of professional developers, there are also scientists(not computer science), other professionals(not IT) and even a couple of hobbyists.

Guilty secret:

My last employer did not use a VCS and I never pushed for the change despite it being needed.

I’m not sure what I should do to mitigate this issue but in meantime I will take action:
If someone wants to provide a definition for an empty entry in the definitions source file (link to the scribble source code) reply to this thread with your definition and I’ll do the pull request on your behalf. (I will credit you if you provide your name or handle)

In the long term I’ll probably use a google form or similar that doesn’t require a login.

PS Empty entries in the scribble source linked above look like this:

@glossary-entry{Comprehension}

  @level-basic

@glossary-entry{Cons cell}

  @level-basic

See @secref*["Pair" 'glossary]

@glossary-entry{Continuation}

  @level-advanced

@sschwarzer has extended scribble to make this easier to update.

2 Likes
15

I can even teach you how to credit the person as the author of the commit if they are comfortable submitting a username/email address :slight_smile:

I do agree with everyone's points about the barrier to entry; OTOH, I can see sschwarzer's points as fairly normal for the open-source community. This is one of the reasons I like hacktoberfest in its origins: it encouraged folks to learn how to contribute, sometimes by working with people that could guide them. It's not that open-source wants to have a high barrier to entry, per se, but that open-source has high standards, perhaps?

At any rate, I think prioritizing content over form is probably the right call (since form is malleable, especially for someone with good git chops that won't mind touching up the commit actually applied but keeping the original author), but that's my opinion.

3 Likes
16

Thank you @simonls and @dstorrs - it is good feedback.

I think I can safely say that all contributions are valued - even if we are not always good at expressing how much we appreciate the contributions. :star_struck:

Updating scribble or even markdown is daunting if you don’t use git and have never used GitHub. Even editing markdown files in the web ui is a confusing experience that assumes a lot of background knowledge.

I think I’ve made this mistake myself - I honestly believe that using GitHub issues for Creative Racket and Quickscript events discouraged some contributors. It is also an issue for the Plot Cookbook.

Maybe a wiki would help?

-- hendrik

17

That escalated quickly. But I'm certainly thankful for the constructive feedback!

I was thinking that compared to what already was in the PR, these would be minor changes, and I guess I intuitively felt @dstorrs would see it like this, too. If my intuition was wrong and the formatting changes feel like a burden, I'm also ok with doing the changes myself. No problem.

Actually, that's always an option. It wouldn't be rational to refuse an already pretty good contribution because there are some formatting issues. Rather I'd use what I get and make any remaining changes myself. What I wrote in the PR comment should be understood as: I'd appreciate these changes, but this isn't a requirement for getting the PR merged.

I think I had intuitively expected to get the additions to the glossary notes in bullet point form. When it didn't happen it occurred to me that having this in bullet point form would make it easier for others to contribute to the same glossary entry, and I pointed out this reasoning in the PR. So this isn't merely a stylistic change in the sense how something is formatted visually.

Although I do have a vision regarding the final product, I'm still trying to find a good way to handle contributions. It's a learning process. The difficulty is to adapt the contribution handling to the specific project. My experience with contributing to other projects doesn't seem to help much here.

I suppose that's what I'm going to do, i.e. accept contributions as they are (unless I don't understand something and need clarification), at least for glossary_notes.md. :slight_smile:

From my perspective the main goal of the Racket Glossary is to make it easier for beginning and intermediate Racket users to understand what are basic, intermediate and advanced concepts, so they're not overwhelmed by stuff where they don't know what's important or even what a concept means in the first place. The use of Markdown is "only" to make contributions easier; in my opinion it's quite unrelated to what the glossary is going to be in the end.

I don't think what I'd like to achieve with the glossary can be done in the Racket Guide, or only as a relatively big change to the contents of the Racket guide (see also this post). That said, my wish would be that eventually the glossary would become part of the official Racket documentation. I have no idea if it should be somehow merged into the Racket Guide, become an appendix to the Racket Guide, become a third document or whether it should stay an independent package. However, I'm thinking making this a standalone package for now would give me/us more freedom with experimenting with the form of the glossary. At the moment, I don't have an idea how the glossary could be combined with the Racket guide. I'm not saying it's not possible, only that I don't know how it could be done.

I really appreciate your help :heart: , but I'm not sure we should already focus on contributions to the main document. The main reason is I'm still experimenting somewhat with the style of the glossary entries and may not be comfortable with merging whole glossary entries yet. I added the Markdown document (glossary_notes.md) not only because of the simpler markup, but more because I'm thinking it's much easier to contribute thoughts/snippets than full glossary entries including examples. Don't get me wrong; I'm not against contributions to glossary.scrbl, but they probably will be more involved than PRs for glossary_notes.md, which makes it more likely that contributors might get frustrated when their contributions aren't merged quickly. :frowning: But if you think we should try it, then let's try it. :slight_smile:

1 Like
18

I saw your post only now after writing my reply to posts further up.

I so agree with what you wrote. When I enter a PR for a project, I consider it completely normal that it won't be the final version. For me it's natural that a PR goes through potentially several iterations; it's part of the contribution process.

On the other hand, I now have more empathy with people who feel different about this and I'm willing to adapt, at least regarding the notes file. :slight_smile:

Edit:

I thought about this before making the glossary a repository. My experience is that the Racket wiki rarely comes up in web searches. The best glossary isn't useful if it can't be found by those who need it. Finding the glossary on the Racket documentation page is much more likely. (I haven't submitted the glossary to the package server yet. I plan to do this once the "basic" category is mostly complete.)

Moreover, I'd like to have some coherence in the writing style between the glossary entries, which would be quite difficult to achieve in a wiki, I think.

19

The wiki existing is good for some things but as part of GitHub it has many of the same disadvantages.

I really like the structure and integration with the racket documentation that the Glossary offers. (Thank you @sschwarzer )

I owe Stefan an apology because I reacted badly to initial attempts to simplify submissions.

Stephen

1 Like
20

It does not need to be part of github. There's foswiki, whihc can be hosted on any server.

Of course that would need administration, which has been a problem on our mailing list in the past.

Aren't there free wiki services?

-- hendrik

1 Like