diff --git a/README.md b/README.md
index a7bd86b..17cc976 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,18 @@
-# esphome-custom-component-examples
+# ESPHome custom component examples
+
+This repository provides examples and basic empty components that can be used as templates to quickly develop your own custom components for the splendid [ESPHome](https://esphome.io/) ESP8266/ESP32 home automation system.
+
+## How to use
+All sample components can be found in the `custom_components` directory. The `test_*.yaml` files provide configuration examples for the various custom components. To use a particular component for your project, do the following:
+
+
+- Create a `custom_components` directory in your esphome configuration directory (the directory where your ```.yaml``` files are)
+
+- Copy the directory of the empty component to `custom_components` in its entirety, so you end up with e.g. `custom_components/empty_sensor/`
+
+- Find the configuration entry for the empty component in `test_empty.yaml` and copy it into your own `.yaml` file.
+
+- Compile with `esphome your_config.yaml compile` (change `your_config.yaml` to your own `.yaml` file) or compile with the dashboard.
+
+- No errors? Great! You can now start modifying the empty component into your own custom component.
+
diff --git a/device.yaml b/device.yaml
index 62a6435..e188145 100644
--- a/device.yaml
+++ b/device.yaml
@@ -1,3 +1,5 @@
+# this is just a simple test device setup that's used to compile and test the examples
+
 esphome:
     name: custom_components_test
     platform: ESP8266
diff --git a/test_empty.yaml b/test_empty.yaml
index 14ad7f9..42966bc 100644
--- a/test_empty.yaml
+++ b/test_empty.yaml
@@ -1,5 +1,8 @@
+# this configuration file has all empty custom components set up.
+# use 'esphome test_empty.yaml compile' to build. 
+
 packages:
-  device: !include device.yaml
+  device: !include device.yaml # include our test device setup
 
 sensor:
   - platform: empty_sensor