diff --git a/README.md b/README.md
index 98248b3..8fc90b0 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 [![Psalm coverage](https://shepherd.dev/github/danog/better-prometheus/coverage.svg)](https://shepherd.dev/github/danog/better-prometheus)
 [![Psalm level 1](https://shepherd.dev/github/danog/better-prometheus/level.svg)](https://shepherd.dev/github/danog/better-prometheus)
-![License](https://img.shields.io/github/license/danog/better-prometheus)
+![License](https://img.shields.io/github/license/danog/better-prometheus?v)
 
 A better Prometheus library for PHP applications.  
 
diff --git a/docs/index.md b/docs/index.md
deleted file mode 120000
index 32d46ee..0000000
--- a/docs/index.md
+++ /dev/null
@@ -1 +0,0 @@
-../README.md
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..8fc90b0
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,90 @@
+# better-prometheus
+
+[![Psalm coverage](https://shepherd.dev/github/danog/better-prometheus/coverage.svg)](https://shepherd.dev/github/danog/better-prometheus)
+[![Psalm level 1](https://shepherd.dev/github/danog/better-prometheus/level.svg)](https://shepherd.dev/github/danog/better-prometheus)
+![License](https://img.shields.io/github/license/danog/better-prometheus?v)
+
+A better Prometheus library for PHP applications.  
+
+Offers a modern, clean PHP 8.1 API, with support for **default label values**, based on and compatible with the original `promphp/prometheus_client_php` library.   
+
+## Installation
+
+```bash
+composer require danog/better-prometheus
+```
+
+## Usage
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+
+use danog\BetterPrometheus\BetterCollectorRegistry;
+use Prometheus\Storage\InMemory;
+use Prometheus\Storage\Redis;
+
+$adapter = new InMemory;
+// Any other promphp adapter may also be used...
+// $adapter = new Redis();
+
+$registry = new BetterCollectorRegistry($adapter);
+
+// Note the difference with promphp: the labels are keys => values, not just keys.  
+$counter = $registry->getOrRegisterCounter(
+    'test',
+    'some_counter',
+    'it increases',
+    // Note: these are default label key+values, they will be sent verbatim, no changes
+    ['someLabel' => 'defaultValue']
+);
+
+// Specify some additional labels post-construction like this (both keys and values)...
+$counter->incBy(3, ['type' => 'blue']);
+
+// ...or add some more default labels to the counter, creating a new counter:
+$newCounter = $counter->addLabels(['someOtherLabel' => 'someOtherDefaultValue']);
+assert($newCounter !== $counter); // true
+$counter->incBy(3, ['type' => 'blue']);
+
+
+
+// Gauges can also be used
+$gauge = $registry->getOrRegisterGauge(
+    'test',
+    'some_gauge',
+    'it sets',
+    ['someLabel' => 'defaultValue']
+);
+$gauge->set(2.5, ['type' => 'blue']);
+
+
+
+// As well as histograms
+$histogram = $registry->getOrRegisterHistogram(
+    'test',
+    'some_histogram',
+    'it observes',
+    ['someLabel' => 'defaultValue'],
+    // [0.1, 1, 2, 3.5, 4, 5, 6, 7, 8, 9]
+);
+$histogram->observe(3.5, ['type' => 'blue']);
+
+
+// And suummaries
+$summary = $registry->getOrRegisterSummary(
+    'test',
+    'some_summary',
+    'it observes a sliding window',
+    ['someLabel' => 'defaultValue'],
+    // 84600,
+    // [0.01, 0.05, 0.5, 0.95, 0.99]
+);
+
+$summary->observe(5, ['type' => 'blue']);
+```
+
+## API documentation
+
+See [here &raquo;](https://github.com/danog/better-prometheus/blob/master/docs/docs/index.md) for the full API documentation.  
\ No newline at end of file