Developer's guide: Include resources for managing cognitive overload in Sage development

sagemath / sage

Main repository of SageMath

https://www.sagemath.org

Other

1.34k stars 452 forks source link

Developer's guide: Include resources for managing cognitive overload in Sage development #36803

Open mkoeppe opened 9 months ago

mkoeppe commented 9 months ago

Problem description:

too much cognitive noise, all these packages and PRs and discussions [...]
It doesn't help that the "fun" and "no fun" [packages are] mixed up in one place, in alphabetical order, no structure whatsoever.
In a too noisy workplace one gets easily distracted and irritated

Originally posted by @dimpase in https://github.com/sagemath/sage/issues/36777#issuecomment-1837277961

As part of our goal to make the Sage development community more inclusive, we expand the developer's guide with strategies, resources, tools for managing cognitive overload in Sage development.

mkoeppe commented 9 months ago

From my personal experience, GitHub Issues and PRs are excellent tools for managing attention / focus.

An important part is that the scope of a PR is defined clearly in its description, and narrowed whenever necessary. Experienced developers know how to set the scope properly, and can recognize when the scope (in their own or others' PRs) needs to be narrowed.

We may need to revise our Reviewer's Guide to emphasize the importance of scope of a PR.

In particular, we should explain that reviewers need to use restraint when discussing topics outside of the scope of the PR in the comments of the PR. Although sometimes the "big picture" needs to inform decisions and discussions on a PR, there is the danger of creating distractions -- which can create cognitive overload for PR author and other reviewers.

roed314 commented 9 months ago

Unfortunately, I'm not able to mediate between the two of you right now, since I'm at an AIM workshop this week and have a grant deadline on Thursday. I've asked the other members of the sage-abuse list to take a look, and I will return when I can.

mkoeppe commented 9 months ago

@williamstein Could you please delete the comments here that clearly violate our CoC, as reported by me to sage-abuse 2 days ago? Like you did in #36827 (https://github.com/sagemath/sage/issues/36827#issuecomment-1843568427). (I've taken screenshots.)

williamstein commented 9 months ago

@williamstein Could you please delete the comments here that clearly violate our CoC, as reported by me to sage-abuse 2 days ago? Like you did in #36827 (#36827 (comment)). (I've taken screenshots.)

Done. I just deleted all comments in this thread that added nothing and made me personally uncomfortable.

mkoeppe commented 7 months ago

Another approach to help with the cognitive noise from > 5000 open issues may be to curate / design contribution activities with sufficiently narrow focus.

A first version: https://github.com/sagemath/sage/wiki#suggested-activities

saraedum commented 6 months ago

Could somebody explain what is "disputed" about this issue? (I am not sure what that label means on an issue actually.) Maybe it can be removed? (It can show up when people look for things that are waiting for a vote. But there's nothing to vote on here.)

saraedum commented 5 months ago

I am removing the disputed label here since there is nothing that requires a vote. Also, as discussed by the sage-conduct committee, we changed the disputed label to make it clear that it is now about PRs looking for a vote.

If you want to point out comments that you think violate our Code of Conduct, then such violations should be reported to the committee. We will then decide whether to hide/delete these comments.