diff --git a/docs/markdown/Custom-build-targets.md b/docs/markdown/Custom-build-targets.md
index f0b50d8fe..76bf9390d 100644
--- a/docs/markdown/Custom-build-targets.md
+++ b/docs/markdown/Custom-build-targets.md
@@ -29,14 +29,15 @@ it does for source generation.
 
 See [Generating Sources](Generating-sources.md) for more information on this topic.
 
-## Details on compiler invocations
+## Details on command invocation
 
 Meson only permits you to specify one command to run. This is by
 design as writing shell pipelines into build definition files leads to
-code that is very hard to maintain. If your compilation requires
+code that is very hard to maintain. If your command requires
 multiple steps you need to write a wrapper script that does all the
-necessary work. When doing this you need to be mindful of the
-following issues:
+necessary work.
+
+When doing this you need to be mindful of the following issues:
 
 * do not assume that the command is invoked in any specific directory
 * a target called `target` file `outfile` defined in subdir `subdir`
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index c28939739..1d0bb9284 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -397,6 +397,10 @@ the following special string substitutions:
 The returned object also has methods that are documented in the
 [object methods section](#custom-target-object) below.
 
+**Note:** Assuming that `command:` is executed by a POSIX `sh` shell is not
+portable, notably to Windows. Instead, consider using a `native: true`
+[executable()](#executable), or a python script.
+
 ### declare_dependency()
 
 ``` meson