diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 98824059..3e2511a8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,25 +1,62 @@
-# How to contribute
+# How to Contribute
 
-We love you to contribute to this project by filing bugs, helping others on the [issue tracker](https://github.com/bpmn-io/bpmn-js/issues), by contributing features/bug fixes through pull requests or by helping out in our [forums](https://forum.bpmn.io/).
+Great to see you! Help us out by [filing bugs or feature requests](#working-with-issues), assisting others in our [forums](https://forum.bpmn.io/) or by [contributing improvements](#contributing-improvements).
 
 
-## Creating issues
+## Table of Contents
 
-We use our [issue tracker](https://github.com/bpmn-io/bpmn-js/issues) for project communication.
-When using the issue tracker:
+* [Working with Issues](#working-with-issues)
+    * [Creating an Issue](#creating-an-issue)
+    * [Helping out](#helping-out)
+* [Contributing Improvements](#contributing-improvements)
+    * [Setting up the Project locally](#setting-up-the-project-locally)
+    * [Discussing Code Changes](#discussing-code-changes)
+    * [Creating a Pull Request](#creating-a-pull-request)
 
-* Be descriptive when creating an issue (what, where, when and how does a problem pop up)?
-* Attach steps to reproduce (if applicable)
-* Attach code samples, configuration options or stack traces that may indicate a problem
+
+## Working with Issues
+
+We use our [issue tracker](https://github.com/bpmn-io/bpmn-js/issues) for project communication, discussion and planning.
+
+
+### Creating an Issue
+
+Help others to understand your request:
+
+* Be clear whether you [file a bug](#reporting-a-bug) or [suggest a new feature/improvement](#suggesting-a-feature)
+* Be descriptive when reporting (what, where, when and how)
+
+
+#### Reporting a Bug
+
+Help us to understand and reproduce your issue:
+
+* Attach your environment (browser, bpmn-js version)
+* Attach steps to reproduce
+* Attach code samples, configuration options or stack traces that provide the necessary context
+
+If possible, try to build an example that reproduces your problem. Use [this JSFiddle](https://jsfiddle.net/kxqy09gf/) as a starting point or put a running demo up on [GitHub](https://github.com/).
+
+
+#### Suggesting a Feature
+
+* Provide the necessary context that allows us to understand how your proposal improves our library
+
+
+### Helping out
+
+* Share your perspective on issues
 * Be helpful and respect others when commenting
 
-Create a pull request if you would like to have an in-depth discussion about some piece of code.
 
+## Contributing Improvements
 
-## Setting up the project locally
+Learn how to setup the project locally, make changes and contribute bug fixes and new features through pull requests.
+
+### Setting up the Project
 
 The project development runs on top of the [diagram-js](https://github.com/bpmn-io/diagram-js) master branch. The following code snippet sets up both libraries linking diagram-js to bpmn-js.
-    
+
     mkdir bpmn.io
     cd bpmn.io
 
@@ -28,17 +65,22 @@ The project development runs on top of the [diagram-js](https://github.com/bpmn-
 
     git clone git@github.com:bpmn-io/bpmn-js.git
     (cd bpmn-js && npm install && npm link ../diagram-js)
-    
+
     // Run the test suite
-    grunt
-    
+    npm test
+
     // Running the test suite with every file change
-    TEST_BROWSERS=(Chrome|Firefox|IE) grunt auto-test
+    TEST_BROWSERS=(Chrome|Firefox|IE) npm run dev
 
 
-## Creating pull requests
+### Discussing Code Changes
 
-We use pull requests for feature discussion and bug fixes. If you are not yet familiar on how to create a pull request, [read this great guide](https://gun.io/blog/how-to-github-fork-branch-and-pull-request).
+Create a [pull request](#creating-a-pull-request) if you would like to have an in-depth discussion about some piece of code.
+
+
+### Creating a Pull Request
+
+We use pull requests for feature additions and bug fixes. If you are not yet familiar on how to create a pull request, [read this great guide](https://gun.io/blog/how-to-github-fork-branch-and-pull-request).
 
 Some things that make it easier for us to accept your pull requests
 
@@ -47,9 +89,12 @@ Some things that make it easier for us to accept your pull requests
     * single-quotes
     * ...
 * The code is tested
-* The `grunt` build passes (executes tests + linting)
+* The `npm run all` build passes (executes tests + linting)
 * The work is combined into a single commit
 * The commit messages adhere to our [guideline](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y)
 
 
 We'd be glad to assist you if you do not get these things right in the first place.
+
+
+:heart: from the bpmn.io team.
\ No newline at end of file