1 files changed, 69 insertions, 0 deletions
diff --git a/doc/app-developers.md b/doc/app-developers.md
new file mode 100644
index 0000000..dad5da7
--- /dev/null
+++ b/doc/app-developers.md
@@ -0,0 +1,69 @@
+Tools in GNOME Software for application developers
+==================================================
+
+GNOME Software is often where users will first come into contact with an
+application which they might later install, so the impression the user gets of
+that application is important. Application developers want to see how their
+application will appear in GNOME Software, and to have some control over it.
+
+GNOME Software provides some tools to help with this.
+
+If there is a supported tool which is not in this document, please
+[submit a merge request](https://gitlab.gnome.org/GNOME/gnome-software/-/merge_requests/new)
+to document it.
+
+Metainfo/Appstream
+------------------
+
+The information about an application comes from its metainfo (or, as it was
+previously known: appdata) file. Metainfo files for multiple applications are
+concatenated into ‘appstream’ files. Almost all of the customisation which GNOME
+Software provides for applications comes from information in metainfo or
+appstream files.
+
+So the first thing to check for your application is that its metainfo file is
+complete and valid. See the
+[metainfo file specification](https://www.freedesktop.org/software/appstream/docs/).
+
+To validate your metainfo file, run
+```
+appstreamcli validate /path/to/app.metainfo.xml
+```
+
+You can add this as a unit test to your application by adding the following to
+the appropriate `meson.build` in your application:
+```
+metainfo_file = files('com.example.MyApp.metainfo.xml')
+appstreamcli = find_program('appstreamcli', required: false)
+if appstreamcli.found()
+  test (
+    'Validate metainfo file',
+    appstreamcli,
+    args: ['validate', '--no-net', metainfo_file],
+  )
+endif
+```
+
+Context tiles
+-------------
+
+The context tiles which are shown on an application’s details page in GNOME
+Software are derived from the application’s metainfo.
+
+There’s more detailed information about them, and the information they are built
+from, [on the GNOME Software wiki](https://gitlab.gnome.org/GNOME/gnome-software/-/wikis/Software-metadata).
+
+Previewing the details page for an application
+----------------------------------------------
+
+GNOME Software allows previewing how an application will appear, by loading its
+metainfo file directly. This allows previewing in-progress changes to an
+application without publishing it to a repository.
+
+Do this with the `--show-metainfo` argument:
+```
+gnome-software --show-metainfo=/path/to/app.metainfo.xml,icon=/path/to/icon.png
+```
+
+This will show the application in the details page of GNOME Software, and will
+also display it in the featured carousel on the overview page.