Simplify Good First Issues

Good-First-Issues.md

@@ -9,38 +9,26 @@
 
 ## Criteria
 
-To label an issue as a [good first issue][] is it must be:
+To label an issue as a [good first issue][] it should:
 
-* reasonably self-contained
+* follow the [issue template](https://raw.githubusercontent.com/sbt/sbt/1.x/ISSUE_TEMPLATE.md)
-* approachable by a first time contributor (a good entry point)
+* be an accepted feature/enhancement request or a confirmed (and hopefully reproduceable) bug
-* should take an experienced maintainer 15-20 minutes to solve, and therefore a newcomer about 1-2 hours
+* be approachable by a first time contributor, a good measure is it should takes a maintainer 20 minutes to
+  resolve (which translates to 1-2 hours for a newcomer)
 
-## How-to write a good first issue (as a maintainer)
+## Mentoring Instructions
 
-As a maintainer these are the steps that should be taken to convert an issue (e.g a [help wanted][] issue) so
+A [good first issue][] should include mentoring instructions that layout the steps to take to resolve an issue.
-that it's ready for a new contributor do the following:
 
-1. get familiar with the issue, and some of the associated code/tests/docs
+Steps:
-2. make sure the [issue template](https://raw.githubusercontent.com/sbt/sbt/1.x/ISSUE_TEMPLATE.md) is followed (steps/problem/explanation/notes) so it's clear what is wrong and/or
-   what needs to be different
-3. make sure the issue is still valid, e.g the bug is reproducable
-4. make sure the purpose/relevance of the issue/change is clear (this helps motivate participation)
-5. add links to relevant code (don't link too huge code blocks or too many links - it gets overwhelming), giving
-   basic explanation of the code behaviour and structure, and explaining the context of the issue/change: how it
-   fits in the big picture
-6. add links to any relevant documentation about either the issue or the code (again not too many links)
-7. explain how to solve the issue, either with the answer and a link to the line(s) to change, or with hints and
-   suggestions to possible solutions and (specify which "solutions" are not acceptable, if any)
-8. add links to pre-existing tests and give tips on how to test the change (if possible)
-9. detail who the contributor can ask for help, and by which means ([sbt/sbt-contrib][], issue comments, etc)
-10. make sure that any additional steps to take are explained or mentoring advice is given
-11. finally, review the issue and see if you can make it more friendly and/or concise
 
-In effect it should actually take longer to write the the issue than to fix it yourself (as an experienced
+1. **Links**: Link to the relevant code, PRs, issue threads, docs, etc
-maintainer), but that extra time is an investment in [making sbt easier to contribute to][].
+2. **Solution**: Add comments/hints on how to resolve the issue (call out "non-solutions" if relevant)
+3. **Testing**: Try and give testing tips, ideally link to prior art
+4. **Help**: Explain how to ask for help (e.g ping @eed3si9n in the issue and/or on [sbt/sbt-contrib][])
+5. **Motivation** (optional): Explain the change's relevance or purpose (to motivate the contribution)
+6. **Background** (optional): Explain the code's behaviour, structure, or context
 
-By:
+It's common that it takes longer to write mentoring instructions than to fix it yourself (as an experienced
-* providing step-by-step instructions on how to make the change and submit it
+maintainer) - this is an investiment in [making sbt easier to contribute to][] and a potential long-term
-* making sure that all the tools that first time contributors need to hack are ready and immediately available
+contributor, possibly maintainer.
-* and that every roadblock gives them a chance to get distracted is dealt with
-we can make a big impact on knowledge sharing and contributions to sbt.