Merge pull request #1530 from opensafely-core/iaindillingham/merge-in…

…troduction Move and rework remaining introductory content
opensafely-core · Aug 24, 2023 · efbed3f · efbed3f
2 parents 7ad92d9 + 1657d97
commit efbed3f
Show file tree

Hide file tree

Showing 10 changed files with 58 additions and 121 deletions.
diff --git a/...ce-for-existing-cohort-extractor-users.md → ...ce-for-existing-cohort-extractor-users.md b/...ce-for-existing-cohort-extractor-users.md → ...ce-for-existing-cohort-extractor-users.md
@@ -37,4 +37,3 @@ the content here may be less relevant for you.
 ## How do I replicate a certain data query pattern from cohort-extractor in ehrQL, or migrate my study definition to a dataset definition?
 
 * For now, consult the [ehrQL examples](../how-to/examples.md) which may cover what you want to do.
-* You can also [ask us for help](getting-help.md).
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
@@ -1,5 +1,6 @@
 The explanation provides theoretical knowledge for studying ehrQL.
 
-* [ehrQL backend tables](explanation/backend-tables.md)
-* [ehrQL output formats](explanation/output-formats.md)
-* [Using ehrQL in OpenSAFELY projects](explanation/using-ehrql-in-opensafely-projects.md)
+* [ehrQL backend tables](backend-tables.md)
+* [ehrQL output formats](output-formats.md)
+* [Using ehrQL in OpenSAFELY projects](using-ehrql-in-opensafely-projects.md)
+* [Guidance for existing cohort-extractor users](guidance-for-existing-cohort-extractor-users.md)
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -1,4 +1,4 @@
 The how-to guides provide practical steps for working with ehrQL in your project.
 
-* [Using ehrQL to answer specific questions](how-to/examples.md)
-* [Resolving ehrQL errors](how-to/errors.md)
+* [Using ehrQL to answer specific questions](examples.md)
+* [Resolving ehrQL errors](errors.md)
diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
 *ehrQL* (*err-kul*), the **Electronic Health Records Query Language**,
 is a programming language and command line interface designed for the specific application domain of EHR data.
-Researchers create **dataset definitions** with the programming language
+Researchers write **dataset definitions** with the programming language
 and execute them with the command line interface to generate **one row per patient datasets**.
 
 ehrQL allows researchers to access data sources from primary and secondary care,
@@ -37,14 +37,53 @@ You can navigate between them by:
 ## Asking for help
 
 If need help with ehrQL or ehrQL's documentation,
-then ask for help on the
+then please ask for help on the
 [#ehrql-support](https://bennettoxford.slack.com/archives/C04DVD1UQC9)
 Slack channel.
-(If you're unsure how to join, then ask your co-pilot.)
+(If you're unsure how to join, then please ask your co-pilot.)
+
+## Example
+
+The following dataset definition is written in ehrQL:
+
+```python
+from ehrql import Dataset
+from ehrql.tables.beta.core import patients, medications
+
+dataset = 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.med_date = latest_asthma_med.date
+dataset.med_code = latest_asthma_med.dmd_code
+```
+
+Notice that the dataset will be restricted to the population of patients born on or before 31st December 1999.
+It will contain two columns: `med_date` and `med_code`.
+`med_date` is the date, and `med_code` is the code, of the latest (most recent) asthma medication.
+Asthma medications will be restricted to those with the dm+d codes `39113311000001107` and `39113611000001102`.
+
+When the dataset definition is executed with the command line interface,
+the command line interface generates a one row per patient dataset.
+For example, it may generate the following dummy dataset:
+
+| `patient_id` | `med_date` | `med_code`        |
+|--------------|------------|-------------------|
+| 1            | 2018-09-21 | 39113311000001107 |
+| 2            | 2014-01-11 | 39113611000001102 |
+| 4            | 2017-05-11 | 39113611000001102 |
+| 5            |            |                   |
 
 ## ehrQL replaces cohort-extractor
 
 Whilst cohort-extractor will be supported for projects created before June 2023,
 new projects should use ehrQL.
 For more information,
-read the [guidance for existing cohort-extractor users](introduction/guidance-for-existing-cohort-extractor-users.md).
+please read the [guidance for existing cohort-extractor users](explanation/guidance-for-existing-cohort-extractor-users.md).
diff --git a/docs/introduction/introduction-to-concepts.md b/docs/introduction/introduction-to-concepts.md
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -1,7 +1,7 @@
 The reference provides theoretical knowledge for working with ehrQL in your project.
 
-* [ehrQL language](reference/language.md)
-* [ehrQL language features](reference/features.md)
-* [ehrQL backends](reference/backends.md)
-* [ehrQL schemas](reference/schemas.md)
-* [ehrQL command line interface](reference/cli.md)
+* [ehrQL language](language.md)
+* [ehrQL language features](features.md)
+* [ehrQL backends](backends.md)
+* [ehrQL schemas](schemas.md)
+* [ehrQL command line interface](cli.md)
diff --git a/docs/tutorial/dataset-definition-concepts.md b/docs/tutorial/dataset-definition-concepts.md
@@ -1,6 +1,5 @@
 This page explains several important concepts that you should understand
 in order to write a dataset definition.
-It builds on the [introduction to ehrQL concepts](../introduction/introduction-to-concepts.md).
 
 ## An example dataset definition
 

diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md
@@ -1,5 +1,5 @@
 The tutorial provides practical steps for studying ehrQL.
 
-* [Installation and setup of ehrQL](tutorial/installation-and-setup.md)
-* [Running ehrQL](tutorial/running-ehrql.md)
-* [ehrQL concepts in depth](tutorial/dataset-definition-concepts.md)
+* [Installation and setup of ehrQL](installation-and-setup.md)
+* [Running ehrQL](running-ehrql.md)
+* [ehrQL concepts in depth](dataset-definition-concepts.md)
diff --git a/docs/tutorial/installation-and-setup.md b/docs/tutorial/installation-and-setup.md
@@ -5,8 +5,6 @@ This page guides you through:
 * downloading a directory of dummy data that we will use
   for demonstrations in the rest of the documentation.
 
-It assumes that you have already read the short [Introduction to ehrQL concepts](../introduction/introduction-to-concepts.md).
-
 ## Working with ehrQL
 
 ### ehrQL is run via a command-line interface
@@ -118,10 +116,6 @@ Did you see something similar?
 then everything is set up correctly.
 You can continue with the rest of this tutorial.
 
-:x: If you do not see similar help text to above or you get an error,
-please [contact us](../introduction/getting-help.md)
-and we can help you get started.
-
 ## Downloading some dummy data
 
 Before running queries against real data in an OpenSAFELY backend,

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -12,9 +12,6 @@ docs_dir: docs
 
 nav:
   - ehrQL: index.md
-  - Introduction:
-    - Guidance for existing cohort-extractor users: introduction/guidance-for-existing-cohort-extractor-users.md
-    - Introduction to ehrQL concepts: introduction/introduction-to-concepts.md
   - Tutorial:
     - Tutorial: tutorial/index.md
     - Installation and setup of ehrQL: tutorial/installation-and-setup.md
@@ -36,6 +33,7 @@ nav:
     - ehrQL backend tables: explanation/backend-tables.md
     - ehrQL output formats: explanation/output-formats.md
     - Using ehrQL in OpenSAFELY projects: explanation/using-ehrql-in-opensafely-projects.md
+    - Guidance for existing cohort-extractor users: explanation/guidance-for-existing-cohort-extractor-users.md
 
 theme:
   name: material