diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md
index 9477b292c..ccdb1f2b2 100644
--- a/docs/markdown/Gnome-module.md
+++ b/docs/markdown/Gnome-module.md
@@ -298,9 +298,23 @@ VAPI or Vala binaries.
 
 ### gnome.yelp()
 
+```meson
+  gnome.yelp(id: string, sources: ...string, sources: []string, media: []string,
+             languages: []string, symlink_media: bool = true): void
+```
+
 Installs help documentation using Yelp. The first argument is the
 project id.
 
+Additionally, sources can be passed as additional positional arguments. This
+was, however, undocumented and never officially supported. Due to a longstanding
+bug, passing sources as a keyword argument will result in the positional
+argument sources to be ignored. *since 0.60.0* A warning is raised in this case.
+
+*Since 0.60.0* the use of the positional argument sources has been deprecated,
+and the "sources" keyword argument should be used instead. The passing of
+sources as positional arguments will be removed in the future.
+
 This also creates two targets for translations
 `help-$project-update-po` and `help-$project-pot`.
 
diff --git a/docs/markdown/snippets/gnome_yelp_sources.md b/docs/markdown/snippets/gnome_yelp_sources.md
new file mode 100644
index 000000000..3633d17ea
--- /dev/null
+++ b/docs/markdown/snippets/gnome_yelp_sources.md
@@ -0,0 +1,6 @@
+## gnome.yelp variadic argument deprecation
+
+`gnome.yelp` previously allowed sources to be passed either as variadic
+arguments or as a keyword argument. If the keyword argument was given the
+variadic arguments would be silently ignored. This has changed in 0.60.0, the
+variadic form has been deprecated, and a warning is printed if both are given.
diff --git a/mesonbuild/modules/gnome.py b/mesonbuild/modules/gnome.py
index a6c0e1b2c..739faec76 100644
--- a/mesonbuild/modules/gnome.py
+++ b/mesonbuild/modules/gnome.py
@@ -33,7 +33,7 @@ from ..mesonlib import (
     join_args, HoldableObject
 )
 from ..dependencies import Dependency, PkgConfigDependency, InternalDependency
-from ..interpreterbase import noPosargs, noKwargs, permittedKwargs, FeatureNew, FeatureNewKwargs, FeatureDeprecatedKwargs
+from ..interpreterbase import noPosargs, noKwargs, permittedKwargs, FeatureNew, FeatureNewKwargs, FeatureDeprecatedKwargs, FeatureDeprecated
 from ..interpreterbase import typed_kwargs, KwargInfo, ContainerTypeInfo
 from ..programs import ExternalProgram, OverrideProgram
 from ..build import CustomTarget, CustomTargetIndex, GeneratedList
@@ -969,12 +969,18 @@ class GnomeModule(ExtensionModule):
             raise MesonException('Yelp requires a project id')
 
         project_id = args[0]
+        if len(args) > 1:
+            FeatureDeprecated.single_use('gnome.yelp more than one positional argument', '0.60.0', 'use the "sources" keyword argument instead.')
+
         sources = mesonlib.stringlistify(kwargs.pop('sources', []))
         if not sources:
             if len(args) > 1:
                 sources = mesonlib.stringlistify(args[1:])
             if not sources:
                 raise MesonException('Yelp requires a list of sources')
+        else:
+            if len(args) > 1:
+                mlog.warning('"gnome.yelp" ignores positional sources arguments when the "sources" keyword argument is set')
         source_str = '@@'.join(sources)
 
         langs = mesonlib.stringlistify(kwargs.pop('languages', []))