diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..370d1620
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,53 @@
+# Developing Schemas
+
+You are welcome to contribute to the schemas for Ansible, Zuul and Molecule!
+
+## Extending the schemas
+
+Changes to the schemas need to be made in `src/ansibleschemas/`. They are then
+generated with `tox` in the directory `f/`. The generated files need to be
+included with each commit as that's the way they are published at the moment.
+
+### Updating the Galaxy Platforms
+
+`GALAXY_PLATFORMS` in `src/ansibleschemas/_galaxy.py` lists the commonly known
+platforms and versions available on Galaxy. They can be viewed visiting
+https://galaxy.ansible.com/api/v1/platforms/.
+
+For updating the list of platforms and versions you can set the environment variable
+`DUMP_GALAXY_PLATFORMS` and run `tox`:
+
+```shell
+DUMP_GALAXY_PLATFORMS=1 tox
+```
+
+This will query the API and replace the current list of galaxy platforms.
+
+### Updating dependencies
+
+Run the following command to update dependency lock files `requirements.txt`
+and `package-lock.json`:
+
+```shell
+tox -e deps
+```
+
+
+## Submitting Pull Requests
+
+Fixes and features for schemas will go through the Github pull request process.
+Submit your pull request (PR) against the `main` branch.
+
+
+Here are a few things you can do to help get your pull request accepted faster:
+
+- Check that the following commands run without reporting any errors
+  - python tests: `tox`
+  - validation tests using mocha: `npm test`
+- Write good commit messages. See [How to write a Git commit message](https://chris.beams.io/posts/git-commit/).
+
+
+## Reporting Issues
+
+We welcome your feedback, and encourage you to file an issue when you run into
+a problem.
diff --git a/README.md b/README.md
index 340f27e1..a9bf97f1 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
-# Schemas for Ansible and Zuul
+# Schemas for Ansible, Zuul and Molecule
 
-This project that aims to generate JSON/YAML validation schemas for Ansible
-files as playbooks, tasks, requirements, meta or vars.
+This project aims to generate JSON/YAML validation schemas for Ansible
+files such as playbooks, tasks, requirements, meta or vars and also for
+Zuul and Molecule configuration.
 
 Keep in mind that these schemas will limit your freedom of choice regarding
 the syntax you can use to write Ansible tasks as they do not allow some
@@ -16,14 +17,19 @@ that any file that passed these schemas should be accepted by Ansible.
 * Non builtin modules must be called using `action:` blocks
 * Module arguments are not yet verified but we plan to implement it
 
-As these schemas are experimental, please refrain from reporting bugs but
-feel free to create pull-requests to improve the schema.
+As these schemas are still experimental, creating pull-requests to improve the
+schema is of much greater help. Though you are still welcome to report bugs
+but expect them to take a longer time until someone finds time to fix them.
+
+If you want to help improve the schemas, have a look at the [development
+documentation](CONTRIBUTING.md).
 
 ## Activating the schemas
 
-At this moment installing [Ansible Language for vscode extension](https://marketplace.visualstudio.com/items?itemName=zbr.vscode-ansible)
-will activate these schemas. The file patterns used to trigger their use can be
-seen [here](https://github.com/ansible-community/vscode-ansible/blob/master/package.json#L86)
+At this moment installing [Ansible VS Code Extension by Red Hat]
+(https://marketplace.visualstudio.com/items?itemName=redhat.ansible) will
+activate these schemas. The file patterns used to trigger their use can be seen
+[here](https://github.com/ansible-community/vscode-ansible/blob/master/package.json#L44-L94)
 
 Because these schemas are generic, you can easily use them with any validators
 that support them.