[MRG] Update contributing guidelines and issue templates

[KirstieJane]

Some personal fiddling on top of @betatim's PR #654. All edits up for discussion!

Ready for review ❤️

Changes in this PR:

• Reformatting and added comments to bug_report and feature_request issue templates.
• Added more words around the contributing guidelines via read the docs. Some reformatting but generally a lot of the content is the same, just with a few extra bits and bobs added to make it (I hope) more accessible.
• Added more words to the links in CONTRIBUTING.md to try to nudge folks to go and actually read the documentation.

[betatim]

I think you mean #654, #624 is an old PR.

[betatim]

Thanks!

I think using the word "assigned" implies that there is someone who can tell someone else what to do. At least when I assign someone homework, tasks, etc I expect them to complete those. We don't have the luxury here. Even when I can assign people work I tend to organise for them to self select to work on it because people are for more motivated if they are working on things they wanted to work on. That is the spirit I think should be in someone asking for a feature. They should be creating FOMO around the feature so that everyone wants to work on it and we have to send people away ;)

Maybe we can convert the sentences that refer to assigning work into "use this to advertise/lobby/convince for your feature and help others understand how much effort it would be to make them more likely to choose to work on this" (needs better wording). Basically scoping the work, pointing to potential places that need work, considering what unintended consequences could come of it. However a lot of that work isn't needed if the work won't happen because "out of scope" or what not. So I don't think we should make it that costly to post a feature request.

What I'd like to see from people making feature requests is that they demonstrate that they understand that making changes comes at a cost, involves making trade-offs, that only if it aligns with someone's priorities* will they put effort into this and that they are willing to help with the effort. Basically, has some thought gone into this or is this a "I am frustrated that X is so tricky to do so it needs to change". The extreme version is: do you think the project owes you anything? If yes, please move along.

I'd also remove the say thank you bit. If it is part of the template it feels a bit fake which makes it lose its "magic".

[KirstieJane]

Hey @betatim - Thanks for the comments - they were a little premature because I've tried to capture your points in the guidelines for contributing. I don't think having them in the feature request issue template is the right place - as we discussed on twitter, people are just not going to read them!! 🤦‍♂

I have to head to dinner (SORRY) but there are a few more changes now for you to take a look at. I haven't REALLY got your point about building momentum in there, but maybe there's an additional bullet point that can fit in?

Happy to remove the thank you part. I kinda like it but it might be a little overly radical to expect people to actually say thank you in a new and creative way each time they ask people for free work 😉

[KirstieJane]

Oh - on the "assigned" part. Would "self-assigned" be any better?

Again, the goal is to nudge people to realise that when they ask for something, they are asking someone to do that work....which is basically exactly the same as "assigning" it. So I think I'm quite pro using the word exactly as intended!

But obviously the point of these templates is not to make the maintainers (in you @betatim!) uncomfortable, so happy to adjust/remove!

(Update: decided to be less agressive and just did the rewording!)

[meeseeksmachine]

This pull request has been mentioned on Jupyter Community Forum. There might be relevant details there:

https://discourse.jupyter.org/t/a-proposal-for-jupyterhub-communications/505/23

[betatim]

Again, the goal is to nudge people to realise that when they ask for something, they are asking someone to do that work

I agree this is what people are doing and what their expectation. I'd like to nudge people a bit in the direction of "I am asking a friend to do me a favour" and the mindset you are in when you do that. Which is different from a teacher asking you to do X as a homework.

[KirstieJane]

Tagging @choldgraf because I think he wanted to take a look at this 😸

[choldgraf]

Just a note for future's sake - we've got some content overlap with this (https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html) and this (https://jupyterhub-team-compass.readthedocs.io/en/latest/contributing.html) section of the broader docs. It would be great to find ways to stramline the content between them and make more connections (not in this PR though!)

[choldgraf]

I think these are all really nice additions to the content that's there. It would be great to find ways to generalize some of this content and harmonize it with what we already have in the Jupyter community (see links in the comment I made above). However this is a clear improvement to the contributing docs and I'm +1 after some of the minor comments are addressed. Thanks @KirstieJane !

[KirstieJane]

Ok cool! I think I've incorporated the changes @betatim & @choldgraf! Hope it ends up being helpful!

[emdupre]

This looks great ! One small suggestion, but happy to see these changes as-is. Thanks, @KirstieJane ✨

[betatim]

I made some new inline change suggestions. Two missing words and one about re-adding TIm's only rule of software development :)

Everything else looks great to me -> let's get on the express train to merge city (aka let's merge this and iterate in a new PR if we need to as this is better than what we already have)

[consideRatio]

❤️ @KirstieJane and all who have reviewed this, I get especially happy about this kind of work to hlelp strengthen our community!

[KirstieJane]

Added a couple of changes and responded to some reviews. Thanks everyone!

[choldgraf]

Hey all - my 2 cents on this one: looking at the current level of word-parsing going on, I think it's time to just merge this one in :-)

@KirstieJane, can you ping when you think the code is ready for MRG? Others: if you think there's a reason to hold off merging, then please chime in!

[KirstieJane]

Cooolio! I think this is ready to merge. As it’s to documentation does it need to be added to the change log?

[betatim]

Going to merge ahead of travis tests being done. Thanks a lot everyone for your patience and ideas and effort!

I think a PR adding it to the change log is in order. I'd also suggest a post on discourse to tell people we put effort into this, mention the three different templates and say "this isn't set in stone, let's see how it goes and if you have thoughts please get involved"