diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 0625f96b7..2fc61d53c 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1022,6 +1022,9 @@ Joins the given strings into a file system path segment. For example
 individual segments is an absolute path, all segments before it are
 dropped. That means that `join_paths('foo', '/bar')` returns `/bar`.
 
+**Warning** Don't use `join_paths()` for sources in [`library`](#library) and
+[`executable`](#executable), you should use [`files`](#files) instead.
+
 *Added 0.36.0*
 
 Since 0.49.0 using the`/` operator on strings is equivalent to calling
diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md
index 9ea96c1d9..cf56dd3f4 100644
--- a/docs/markdown/Syntax.md
+++ b/docs/markdown/Syntax.md
@@ -216,6 +216,14 @@ path = pathsep.join(['/usr/bin', '/bin', '/usr/local/bin'])
 path = join_paths(['/usr', 'local', 'bin'])
 # path now has the value '/usr/local/bin'
 
+# Don't use join_paths for sources files, use files for that:
+my_sources = files('foo.c')
+...
+my_sources += files('bar.c')
+# This has the advantage of always calculating the correct relative path, even
+# if you add files in another directory or use them in a different directory
+# than they're defined in
+
 # Example to set an API version for use in library(), install_header(), etc
 project('project', 'c', version: '0.2.3')
 version_array = meson.project_version().split('.')