diff --git a/README.md b/README.md
index 2c1cc501cc02e15eb4b5e209d755b7ae95bf3268..aba30dda74b1cc90e3691efc38ac12e65530c995 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,29 @@
-# SurveyJS quiz widgets
+# SurveyJS Quiz Widgets
+A repository of custom [SurveyJS](https://surveyjs.io/form-library/documentation/overview)
+widgets used for quizzes.
+
+## Available widgets
+- [Fill-in-the-gaps text (selector)](src/widgets/gapfill-select.js)
+- [Fill-in-the-gaps text (open input)](src/widgets/gapfill-open.js)
+
+## Usage
+Each widget is its standalone file in [`src/widgets`](src/widgets), as a
+JavaScript [module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).
+You can simply add it to your source files and [import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#importing_features_into_your_script)
+the widget object :
+```js
+import {gapfillSelectWidget} from "./widgets/gapfill-select.js";
+```
+*(If you don't want to use JS modules, you can also remove the `export` keywords
+and use it as a classic script file)*
+
+Then, before loading your survey's model, register the widget into SurveyJS's
+custom widgets collection :
+```js
+Survey.CustomWidgetCollection.Instance.add(gapfillSelectWidget, gapfillSelectWidget.name);
+```
+And *voilà!* You have a new question type, which can be used in your survey's
+JSON model just like a built-in type.
+
+The rest of the `src` directory is a simple example of how to use these widgets.
+For more info on custom widgets, see the [SurveyJS documentation](https://surveyjs.io/form-library/documentation/customize-question-types/create-custom-widgets#custom-widget-api).
\ No newline at end of file