diff --git a/README.md b/README.md
index 188c7c3..0ecd145 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,45 @@
-This is used by [PyCharm Odoo](https://github.com/trinhanhngoc/pycharm-odoo) to improve
-code completion.
\ No newline at end of file
+# odoo-stubs
+
+> A stub file is a file containing a skeleton of the public interface of that Python module,
+> including classes, variables, functions – and most importantly, their types.
+>
+> https://mypy.readthedocs.io/en/stable/stubs.html 
+
+By using these stubs, IDEs will provide better code completion,
+and static type checkers will provide better reports.
+These stubs should be used in conjunction with:
+- [PyCharm plugin for Odoo](https://plugins.jetbrains.com/plugin/13499-odoo)
+- [Visual Studio Code extension for Odoo](https://marketplace.visualstudio.com/items?itemName=trinhanhngoc.vscode-odoo)
+
+## Usage
+
+### 1. Clone the branch corresponding to the Odoo version
+
+Example, for Odoo 16:
+```
+git clone -b 16.0 https://github.com/odoo-ide/odoo-stubs.git odoo-stubs16
+```
+
+### 2. Configure IDEs
+
+#### PyCharm
+
+First make sure you have attached the [Odoo source code](https://github.com/odoo/odoo)
+to your project.
+Then open `Settings > Project > Project Structure`,
+select the project containing the Odoo source code and click `Add Content Root` to add the odoo-stubs folder.
+
+![PyCharm](images/pycharm.png)
+
+#### Visual Studio Code
+
+Create [`pyrightconfig.json`](https://microsoft.github.io/pyright/#/configuration) in the Odoo source code folder
+(should be the root folder of your workspace) with something like the following example:
+
+```json
+{
+    "stubPath": "path/to/odoo-stubs"
+}
+```
+
+![VSCode](images/vscode.png)
diff --git a/images/pycharm.png b/images/pycharm.png
new file mode 100644
index 0000000..8bd4f7a
Binary files /dev/null and b/images/pycharm.png differ
diff --git a/images/vscode.png b/images/vscode.png
new file mode 100644
index 0000000..0ae89bf
Binary files /dev/null and b/images/vscode.png differ