Racket glossary

[sschwarzer]

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

@simonls

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 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.

@simonls

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".

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.

@simonls

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.

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.

@simonls

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.

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.

@dstorrs

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.

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.

@dstorrs

what you're creating here would be better implemented as part of the Guide, not as a separate document.

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.

@spdegabrielle

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 really appreciate your help , 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. But if you think we should try it, then let's try it.