diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6a5a99e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# Mappersons - Visualize People on a World Map
+
+Mappersons is a web app that allows you to visualize pictures of people on a world map along with their respective tasks and locations. With its intuitive slider feature, users can easily navigate through different calendar weeks to see how locations change over time.
+
+![Mapperson](screenshot.png)
+# Usage
+To use Mappersons, follow these steps:
+
+1. Place square images of people in the `persons` folder. Each person should have a unique filename (e.g. `jane.jpg`, `bob.jpg`, etc.).
+2. Create a `persons.yml` file according section persons.yml
+3. Create a `locations.yml` file according section locations.yml
+4. Run the `python mappersons.py` script to render the map.
+5. Serve the output with `python -m http.server 8080` to make it accessible through a web browser.
+
+## persons.yml
+
+### Structure
+This YAML file has a structure that includes the following fields:
+- `name`: The name of the person or entity.
+- `image`: The image associated with the person or entity.
+- `weeks`: A list of weeks, each containing:
+  - `location`: The location where tasks were performed. Identically to locations.yml
+  - `tasks`: A list of tasks performed during that week at that location.
+
+### Example File Content
+
+```yaml
+---
+- name: Lisa Lurch
+  image: lurch_l.jpg
+  weeks:
+    21/2023:
+      - location: Hamburg
+        tasks:
+          - Test new Feature
+    22/2023:
+      - location: Hamburg
+        tasks:
+          - Maintenance NSP
+- name: Walter Wiesel
+  image: wiesel_w.jpg
+  weeks:
+    21/2023:
+      - location: Teisnach
+        tasks:
+          - Wrap up Ship 1
+    22/2023:
+      - location: Hamburg
+        tasks:
+          - Backoffice Ship 1
+          - Write report
+```
+## locations.yml
+
+This file contains a list of locations with their corresponding latitude and longitude coordinates.
+
+### Structure
+
+The structure of this YAML file is as follows:
+```yaml
+- name: [Name of the location]
+  lat: [Latitude in decimal degrees]
+  lng: [Longitude in decimal degrees]
+```
+### Example File Content
+```yaml
+---
+- name: Hamburg
+  lat: 53.64286
+  lng: 9.9753
+- name: La Spezia
+  lat: 44.1064
+  lng: 9.8439
+- name: Teisnach
+  lat: 49.0301
+  lng: 12.998
+```
diff --git a/screenshot.png b/screenshot.png
new file mode 100644
index 0000000..a0fc5e4
Binary files /dev/null and b/screenshot.png differ