Updates to contributing guidelines

CONTRIBUTING.md

@@ -1,35 +1,45 @@
-## What to contribute
-There are many ways that you can contribute to the Azure IoT SDKs project:
+**The Azure IoT SDKs team wants to hear from you!**
 
-* Submit a bug
-* Submit a code fix for a bug
-* Submit code to add a new platform/language support to the project, or modify existing code
-* Submit additions or modifications to the documentation
-* Submit a feature request
+- [Ask a question](#ask-a-question)
+- [File a bug](#file-a-bug)
+- [Contribute documentation](#contribute-documentation)
+- [Contribute code](#contribute-code)
 
-The key design principle is that the code makes it easy for people to get data from sensors into Azure IoT services.
+# Ask a question
+Our team monitors Stack Overflow, especially the [azure-iot-hub](http://stackoverflow.com/questions/tagged/azure-iot-hub) tag. It really is the best place to ask.
 
-## Contributing Code
-To contribute code you need to issue a Pull Request against the develop branch. All code submissions will be reviewed and tested by the team, and those that meet a high bar for both quality and design/roadmap appropriateness will be merged into the source. Be sure to follow the existing file/folder structure when adding new boards or sensors.
+We monitor the Github issues section specifically for bugs found with our SDK, however we will reply to questions asked using Github issues too.
 
-You must sign a [Contribution License Agreement](https://cla.microsoft.com/) ([CLA](https://cla.microsoft.com/)) before submitting a Pull Request. To complete the CLA, you will need to submit the request via the form and then electronically sign the CLA when you receive the email containing the link to the document.
+# File a bug (code or documentation)
+That is definitely something we want to hear about. Please open an issue on github, we'll address it as fast as possible. Typically here's the information we're going to ask for to get started:
+- What SDK are you using (Node, C, C#, Python, Java?)
+- What version of the SDK?
+- Do you have a snippet of code that would help us reproduce the bug?
+- Do you have logs showing what's happening?
 
-## Big contributions
-If your contribution is significantly big it is better to first check with the project developers in order to make sure the change aligns with the long term plans. This can be done simply by submitting a question via the GitHub Issues section.
+Our SDK is entirely open-source and we do accept pull-requests if you feel like taking a stab at fixing the bug and maybe adding your name to our commit history :) Please mention
+any relevant issue number in the pull request description.
 
-## Things to keep in mind when contributing
-Some guidance for when you make a contribution:
+# Contribute documentation
+For simple markdown files, we accept documentation pull requests submitted against the `master` branch, if it's about existing SDK features.
+If your PR is about future changes or has changes to the comments in the code itself, we'll treat is as a code change (see the next section).
 
-* Add/update the Visio design diagram when required by your change
-* Add/update module requirements as required by your change
-* Add/update unit tests and code as required by your change
-* Make sure you run all the unit tests on the affected platform(s). If the change is in common code, generally running on one platform would be acceptable
-* Run end-to-end tests or simple sample code to make sure the lib works in an end-to-end scenario.
+# Contribute code
+Unlike documentation, we require pull-requests for code to be submitted against the `develop` branch in order to review and run it in our gated build system. We try to maintain a high bar
+for code quality and maintainability, we insist on having tests associated with the code, and if necessary, additions/modifications to the requirement documents.
+
+Also, have you signed the [Contribution License Agreement](https://cla.microsoft.com/) ([CLA](https://cla.microsoft.com/))? A friendly bot will remind you about it when you submit your pull-request.
+
+If you feel like your contribution is going to be a major effort, you should probably give us a heads-up. We have a lot of items captured in our backlog and we release every two weeks, so before you spend the time, just check with us to make
+sure your plans and ours are in sync :) Just open an issue on github and tag it "enhancement" or "feature request"
 
 ## Editing module requirements
-We write detailed module requirements that we trace in the code and unit tests. In order for each small requirement to be traceable it receives an Id. The requirement Id is generated by using a Word macro that is embedded in the requirement document.
+We use requirement documents to describe the expected behavior for each code modules. It works as a basis to understand what tests need to be written.
 
-The following steps describe adding a new requirement:
+Each requirement has a unique tag that is re-used in the code comments to identify where it's implemented and where it's tested. To generate these unique identifiers, we used to use a Microsoft Word macro.
+We are progressively switching to Markdown though, for which we have no macro, therefore we have to be careful about numbering.
+
+The following steps describe adding a new requirement in a Word document:
 
 * Add the requirement text and select it
 
@@ -46,3 +56,5 @@ The following steps describe adding a new requirement:
 * Done!
 
 ![](media/add_requirement/add_requirement_step4.png)
+
+When contributing to markdown requirement docs, you can also use `99` for a developer id, and just increment the last number of the requirement to be unique.