diff --git a/docs/schemas/Demixer.yml b/docs/schemas/Demixer.yml
index 246cd405ca4b06b4da02fcb4aceb5dfa68ffcc44..8a89f879c12bb27beb40645d5cb5b4fb60c5cd52 100644
--- a/docs/schemas/Demixer.yml
+++ b/docs/schemas/Demixer.yml
@@ -1,5 +1,8 @@
 description: >-
-  Demix in the old way.
+  Demix bright sources, i.e. calibrate in the direction of the birght sources and
+  subtract the bright sources from the data. Note that the calibration solution
+  is assumed to be constant over the entire frequency range, so this will only
+  work on relatively small bandwidth (e.g. a single sub-band).
 inputs:
   step_name:
     type: string
@@ -12,16 +15,16 @@ inputs:
   baseline:
     default: "\"\""
     type: string
-    doc: Baselines to demix. See Description of baseline selection parameters `.`
+    doc: Baselines to demix. See :ref:`Description of baseline selection parameters`
   blrange:
     default: []
     type: double[]
-    doc: Baselines to demix. See Description of baseline selection parameters `.`
+    doc: Baselines to demix. See :ref:`Description of baseline selection parameters`
   corrtype:
     default: cross
     type: string
     doc: >-
-      Baselines to demix. Correlation type to match? Must be auto, cross, or an
+      Baselines to demix. Correlation type to match? Must be ``auto``, ``cross``, or an
       empty string `.`
   timestep:
     default: 1
@@ -49,7 +52,7 @@ inputs:
     type: float
     doc: >-
       Time resolution to use when demixing, in seconds. If this is given, and is greater than
-      zero, it overrides `<step>.demixtimestep` `.`
+      zero, it overrides ``<step>.demixtimestep`` `.`
   demixfreqstep:
     default: 0
     type: int
@@ -74,7 +77,7 @@ inputs:
   skymodel:
     default: sky
     type: string
-    doc: Sourcedb (created with `makesourcedb`) with the sky model to calibrate on `.` When the path ends with ``.skymodel`` or ``.txt`` DP3 expects a skymodel file as used by makesourcedb. This makes it possible to directly use a skymodel file without using makesourcedb to convert the file.
+    doc: Sourcedb (created with ``makesourcedb``) with the sky model to calibrate on. When the path ends with ``.skymodel`` or ``.txt`` DP3 expects a skymodel file as used by makesourcedb. This makes it possible to directly use a skymodel file without using makesourcedb to convert the file.
   instrumentmodel:
     default: instrument
     type: string
@@ -99,7 +102,7 @@ inputs:
     default: "\"\""
     type: string
     doc: >-
-      It can be used to specify the name of the source model of the target. If
+      This setting can be used to specify the name of the source model of the target. If
       given, the target source model (its patch in the SourceDB) is taken into
       account when solving; in this case parameter ``othersources`` cannot be given.
       It cannot be given if ``ignoretarget=true``. If not given, the target is
diff --git a/docs/schemas/Description of baseline selection parameters.yml b/docs/schemas/Description of baseline selection parameters.yml
index 2f83560590075ce5e08199fde596bddb1bd1d266..f0e37e6109bba47177226ca1ba2b59095623132d 100644
--- a/docs/schemas/Description of baseline selection parameters.yml	
+++ b/docs/schemas/Description of baseline selection parameters.yml	
@@ -72,11 +72,11 @@ inputs:
   corrtype:
     default: "\"\""
     type: string
-    doc: Correlation type to match? Must be auto, cross, or an empty string (= all) `.`
+    doc: Correlation type to match? Must be ``auto``, ``cross``, or an empty string (= all) `.`
   blrange:
     default: "[]"
     type: double?
-    doc: Zero or more ranges of physical baseline lengths (in m). A baseline matches if its length is within one of the ranges. E.g., ``blrange=[0,10000, 100000, 1e30]`` `.`
+    doc: Zero or more ranges of physical baseline lengths (in m). A baseline matches if its length is within one of the ranges. E.g., ``blrange=[0,10000, 100000, 1e30]`` matches baselines shorter than 10km and baselines longer than 100km `.`
   baseline:
     default: "\"\""
     type: baseline?
diff --git a/docs/schemas/SmartDemixer.yml b/docs/schemas/SmartDemixer.yml
index 27cb16173a508e0aa22fdda7d0184aae84d5e1fd..a1c5da5e194832c23ae46109c53d7712b83c6b7d 100644
--- a/docs/schemas/SmartDemixer.yml
+++ b/docs/schemas/SmartDemixer.yml
@@ -1,5 +1,5 @@
 description: >-
-  Demix in a new, smarter way.
+  Alternative variant of demixing, where not all the sources are demixed during the whole observation.
 inputs:
   type:
     type: string
@@ -19,7 +19,7 @@ inputs:
     default: cross
     type: string
     doc: >-
-      Baselines to demix. Correlation type to match? Must be auto, cross, or an empty string `.`
+      Baselines to demix. Correlation type to match? Must be ``auto``, ``cross``, or an empty string `.`
   target&#46;baseline:
     default: "CS*&"
     type: string
@@ -34,7 +34,7 @@ inputs:
     default: cross
     type: string
     doc: >-
-      Baselines to use in prediction of median target amplitude. Correlation type to match? Must be auto, cross, or an empty string `.`
+      Baselines to use in prediction of median target amplitude. Correlation type to match? Must be ``auto``, ``cross``, or an empty string `.`
   timestep:
     default: 1
     type: integer