Improving Contributing.md

[daveconnis]

Problem

Went through contributing.md doc to edit and find places where people might get confused or drop off. Found multiple typos and misspellings that need to be fixed as well as some possible places that could be reworded or edited for clarity.

Subtasks

• [ ] Add reach out encouragement like the one bolded below after "before you get started."

Before you get started Fork the repo. Read and work through the installation guide. Run the tests. We only take pull requests with passing tests, and it's great to know that you have a >clean slate: ember exam. More information on testing commands can be found here Stuck? Run into an issues doing this? Reach out on slack or email us at [email protected] or [email protected].

• [ ] Fix tone on opening paragraph of "How to tackle a new feature"

How to tackle a new feature If there's already an issue for the feature you want to tackle, how complete is the description? Do >you know what to do next? Are you confident you know what "done" looks like?

This tone sounds really scary to me. It's almost sounds like, "If there's an issue to tackle, if you're not saying yes to these questions you should probably stay away." While these might be good things to ensure, the way this is stated might cause people to drop

• [ ] Replace line in "How to tackle a new feature" paragraph with more newbie friendly tone

Whether you're writing a new issue or improving on an existing issue, be sure to clarify exactly how you expect the finished change to look and work.

Would be more inviting if it were to be stated like:

Whether you're writing a new issue or improving on an existing issue, it’s important to be really clear on how you expect the finished change to look and work. be sure to clarify exactly how you expect the finished change to look and work.

• [ ] Add small explaination in How to refactor Code section:

I'm just thinking that if someone is looking at this for the first time. We might need a quick, "this is what refactoring is" if we don't want that in the doc, maybe we should link to another doc that explains it.

• [ ] Fix typo in "How to Update Dependencies Section" depencency should be dependency
• [ ] Cut word in "How to Write New code"

Try to keep your changes to a max of around 200 lines of code whenever possible. Why do this? >Apparently the more changes incurred in a pull request, the likelier it is that people who review >your code will just gloss over the details. Smaller pull requests get more comments and feedback >than larger ones. Crazy, right?

I'd cut "apparently."

• [ ] Add some newbie friendly anxiety killing wording in "What if I don't know where to help." <What if I don't know how to help? <Not a problem! You can try looking around for issues that say good for new contributors. <Documentation really is a good place to start. If you're still not sure, just join our Slack and flag someone down to pair with you. Someone can help point you in the right direction.

Something like the bolded line to encourage users to join slack or reach out to pair

• [ ] Add newbie encouragement Under "I finished my changes" section

Something like: At this point you're waiting on us. We like to at least comment on, if not accept, pull requests within a week's time. We may suggest some changes or improvements or alternatives. If you think you’re done, but don’t feel confident about your PR, don’t worry! Flag someone down in our slack channel and discuss what’s bothering you or got you stuck.

• [ ] Fix typo in "Using Git Effectively" section

When making code changes with Git, it is best to develop a workflow. Every 'feature', which can be anything from a 1-line change to an entire component, should be done on seperate feature branch. Seperate should be separate.

• [ ] Consider tone in "Using windows/powershell"

If you are a Windows user, you should really be using Powershell as your command line (especially since it adopts bash aliases for most cmd.exe functions).

Might be nitpicky, but "you should really be using" sounds a little condescending. Consider rewriting.

• [ ] Fix typo in "Using windows/powershell"

You'll probably want to keep some sort of Bash emulator on hand. Git comes with it's own bash shell, but its not very good. Fortunately there are a few other great options:

"its" should be "it's"

• [ ] Fix typo in "Using windows/powershell"

Windows Subsystem for Linux More complex to use, but it gives you a full bash shell in an Ubuntu enviornment.

"Enviornment" should be "environment"