Try to make "why we don't want to discuss things" FAQ entry more positive and welcoming

[matta]

I want to share my reaction to the FAQ entry: Why aren't people willing to discuss certain topics, like the file extension or syntax for specific constructs?. I'll also offer my time to come up with a change to address the problems I see (assuming there is some consensus).

My immediate reaction reading this answer was negative. I came away feeling about it as if it said: We decide things, you weren't around, too bad, please go away.

After some thought, I was able to read it as: We decide things, gotta do that in projects ya know?, we try to be consistent and rational and write them down somewhere, regardless you weren't around, try to find out why things are the way they are if you're interested, but, regardless, too bad. Unless you have an incredibly serious reason to give your feedback just stick to clicking on emojis in the discussion board, or just be quiet and try to be happy with the status quo.

...and I can't shake the feeling that this answer is vague enough to be something established community members could keep in their back pocket to "invoke" to shut down conversations without more explanation.

Apologies for the perhaps hyperbolic characterizations :relaxed:, but the above is basically how I experienced reading that answer. I went as far as to share it with my wife and she agreed that the answer had a definitely has a distinctly closed "talk to the hand" power dynamic going on.

Here are the things I think this answer needs to cover to feel respectful, welcoming, etc. (i.e. in line with Carbon's community goals).

1. Short explanations of the community evolution process (proposals, etc.), and link to it.
2. Explain that many design decisions have been made, give the state these things are in a name like "decided" (except I get the impression that many things are in a bit of a fuzzy logic "anything can be revisited, but some more than others" situation, given "Carbon is experimental").
3. Encourage people to go back and read past discussions, proposals, rationale, etc. Ideally before seriously proposing changes. Make these easy to find (currently this is a bit confusing). Finding out why should ideally be easy.
4. Make it clear that questions about why Carbon is the way it is are always welcome (ideally over time the most frequently asked things end up in the FAQ?)
5. ...including a description of how proposals are marked approved or not, where in-flight conversations are happening, where rejected proposals go, etc. (after days of poking around I still don't quite know how to quickly find some of this info...are all things in proposal/p*.md approved? What can I grep for to tell?)
6. Clear description of how people can "give feedback afterward" for decided things (the FAQ currently tells people to either be convinced that the house is on fire and raise an emergency alarm, or find a "reaction" emoji to click on, or just suck it up.)
7. Make it clear the kind of answer community participants can expect from each other when told that a particular issue is "decided" or not currently up for active discussion. E.g. ideally this message should include a link to the specific proposal where it became decided, or even just mention that there is background material to be found with some bread crumbs leading to it.
8. Explain the kinds of "whys" some things are currently decided. I can think of:
   1. Decided "just for now": we've made some decisions with an implicit or explicit intent to revisit them later, especially if they are annoying. Perhaps the .carbon extension and me falls/fell here.
   2. Decided "for experimentation": we've made some decisions that we think have benefits but also might be annoying, and we expect community feedback to prompt a reexamination. Perhaps the requirement that comments must only be preceded by whitespace falls here.
   3. Decided "because we hope to design our way of of the downsides in the future." Whitespace falls here too?
   4. Decided "in clay": we're pretty sure we got it right, but are open to revisiting.
   5. Decided "in sandstone": almost certain we got it right, unlikely to discuss further in the foreseeable future.
   6. Decided "in diamond": barring an unexpected surprise, we think reversing the decision strongly contradicts the project's goals.
9. Make it clear that if a person's particular issue is decided/closed, we still appreciate their feedback, as well as any other work or feedback they'd like to do.

Making the above outline made it clear: that isn't a FAQ answer, that is a fleshed out community guidelines document! But I can't work out how to answer the "why we're not discussing that thing now" question in a friendly, welcoming way without a lot of verbosity.

So help wanted on that.

Thoughts?

[chandlerc]

My main thought is that I agree, this isn't really a FAQ answer any more.

And we do have documents that detail the things you're calling out as needed, even laid out much as you suggest: https://github.com/carbon-language/carbon-lang/blob/trunk/CONTRIBUTING.md#ways-to-contribute

Some of these points seem like places where maybe the existing docs for the evolution process and proposals could improve. But I'm not immediately sure what specific changes would help -- maybe proposing some improved docs there would help? We've been trying our best to document this and make things easy to find, but of course if it isn't working, happy to have more suggestions.

I guess I wonder if some of the reaction is as much to the title of the FAQ entry as anything else?

Would an entry titled "When do we re-visit decisions or re-open discussions?" maybe frame the core new information more helpfully? (Could also potentially suggest a few more minor improovements to the wording based on that FAQ entry.)

[ezzieyguywuf]

Would an entry titled "When do we re-visit decisions or re-open discussions?" maybe frame the core new information more helpfully?

I think so

Could also potentially suggest a few more minor improovements to the wording

I think this is appropriate.

I generally agree with the OP's sentiments and feel that the FAQ entry could use more than a few minor impro🐮vements, however I imagine there's a fine line to be walked here between softening the tone and maintaining forward momentum for the project's goals.

[matta]

@chandlerc I used your "When do we re-visit decisions or re-open discussions?" -- thought it was great as it greatly clarified what this FAQ was trying to address.

Sent a pull request with my best effort. Wish github didn't spam this issue with my work in progress commits made in my own repo grumble grumble.

[ezzieyguywuf]

Wish github didn't spam this issue with my work in progress commits made in my own repo grumble grumble.

Because of this i tend to reference any GitHub issues or PRs in my PR description itself rather than the commit message.

This isn't ideal though as it makes it harder for a future reader to find the cross-reference

I think most githubers just accept the spam as a reality of life

[jonmeow]

I'm closing as resolved by #1848 (Thank you!)