--- a
+++ b/docs/index.md
@@ -0,0 +1,90 @@
+*ehrQL* (rhymes with *circle*), the **Electronic Health Records Query Language**,
+is a query language and software tool designed for working with health data.
+Researchers write **dataset definitions** with the query language
+and execute them with the tool to generate **datasets with one row per patient**.
+
+ehrQL allows researchers to access data sources from primary and secondary care,
+as well as from organisations such as the Office for National Statistics (ONS).
+
+ehrQL standardises data management tasks to promote efficiency,
+reproducibility and transparency while maintaining patient privacy.
+You can find out more about ehrQL's [philosophy and design goals](https://www.bennett.ox.ac.uk/blog/2023/09/why-ehrql/) on the Bennett Institute blog,
+or see some [examples of ehrQL](how-to/examples.md) in action in the documentation.
+
+If you have cumbersome data management tasks which are not currently supported by ehrQL
+then please email us at <bennett@phc.ox.ac.uk> so we can consider how we might extend ehrQL to meet your needs.
+
+## ehrQL's documentation
+
+ehrQL's documentation has four main sections:
+
+1. The [tutorial](tutorial/index.md) provides practical steps for learning ehrQL.
+
+1. The [how-to guides](how-to/index.md) provide practical steps for working with ehrQL in your project.
+
+1. The [reference](reference/index.md) provides background knowledge for working with ehrQL in your project.
+
+1. The [explanations](explanation/index.md) provide background knowledge for learning ehrQL.
+
+### Conventions
+
+* :computer: steps you should follow on the computer you are using for studying or working with ehrQL
+* :notepad_spiral: explanatory information
+* :warning: important information
+* :grey_question: questions for you to think about
+
+### Navigation
+
+The four main sections are written to be read in order.
+You can navigate between them by:
+
+* pressing the ++n++ or ++period++ keys to go to the next page, and the ++p++ or ++comma++ keys to go to the previous page;
+* using the *Previous* and *Next* links in the page footer;
+* referring to the navigation pane to the left of the page and clicking a link.
+
+## Asking for help
+
+If you need help with ehrQL or ehrQL's documentation,
+then please ask for help on the
+[#opensafely-users](https://bennettoxford.slack.com/archives/C01D7H9LYKB)
+Slack channel.
+(If you're unsure how to join, then please ask your co-pilot.)
+
+## A dataset definition
+
+The following dataset definition selects the date and the code of each patient's most recent asthma medication,
+for all patients born on or before 31 December 1999.
+
+```ehrql
+from ehrql import create_dataset
+from ehrql.tables.core import patients, medications
+
+dataset = create_dataset()
+
+dataset.define_population(patients.date_of_birth.is_on_or_before("1999-12-31"))
+
+asthma_codes = ["39113311000001107", "39113611000001102"]
+latest_asthma_med = (
+    medications.where(medications.dmd_code.is_in(asthma_codes))
+    .sort_by(medications.date)
+    .last_for_patient()
+)
+
+dataset.asthma_med_date = latest_asthma_med.date
+dataset.asthma_med_code = latest_asthma_med.dmd_code
+```
+
+When the dataset definition is executed with the command line interface,
+the command line interface generates a dataset with one row per patient.
+For example, it may generate the following dummy dataset:
+
+| patient_id | asthma_med_date |        asthma_med_code |
+| ---------- | --------------- | ---------------------- |
+|          1 |      2023-05-14 | 39113611000001102      |
+|          2 |      2023-05-26 | 39113611000001102      |
+|          3 |      2018-07-23 | 39113311000001107      |
+|          5 |      2004-09-25 | 39113611000001102      |
+|          6 |      2007-04-25 | 39113611000001102      |
+|          7 |      1949-10-18 | 39113311000001107      |
+|          9 |      1966-05-15 | 39113311000001107      |
+|         10 |      1966-03-14 | 39113611000001102      |