diff --git a/docs/self-hosted/advanced-config-file.mdx b/docs/self-hosted/advanced-config-file.mdx
index 0359f3cae..dd20d9b4e 100644
--- a/docs/self-hosted/advanced-config-file.mdx
+++ b/docs/self-hosted/advanced-config-file.mdx
@@ -62,6 +62,7 @@ Where `extsvc.json` contains a JSON object that specifies _all_ of your code hos
   "GITHUB": [
     {
       // First GitHub code host configuration: literally the JSON object from the code host config editor.
+      "displayName": "GitHub.com",
       "authorization": {},
       "url": "https://github.com",
       "token": "...",
@@ -90,6 +91,10 @@ Where `extsvc.json` contains a JSON object that specifies _all_ of your code hos
 
 If you want to _allow_ edits to be made through the web UI (which will be overwritten with what is in the file on a subsequent restart), you may additionally set `EXTSVC_CONFIG_ALLOW_EDITS=true`. **Note** that if you do enable this, it is your responsibility to ensure the configuration on your instance and in the file remain in sync.
 
+### Display names
+
+Each connection can set an optional `displayName`, the name shown in the UI. If omitted, the name is `<KIND> #<position>`, e.g. `GITHUB #2`. Display names must be non-empty and unique within a kind. `displayName` is only available in declarative config.
+
 ### Configuring GitHub Apps declaratively
 
 GitHub Apps can be fully configured via the `EXTSVC_CONFIG_FILE`, eliminating the need to manually add apps through the UI after redeploying an instance.
@@ -299,7 +304,7 @@ As Sourcegraph reads from an `extsvc.json` file it reads from the top level sche
 }
 ```
 
-You can avoid generation of a new config by changing the display name of your UI based config to match the relative display name which will be generated by the new `extsvc.json` file. For Sourcegraph to view a codehost config as already present its `display_name`, `kind`, and `config` **must not** change. You can take a look at these values in the database by running the following SQL query:
+You can avoid generation of a new config by changing the display name of your UI based config to match the relative display name which will be generated by the new `extsvc.json` file, or by setting `displayName` in `extsvc.json` to the current display name of your UI based config. For Sourcegraph to view a codehost config as already present its `kind` and either its `display_name` or its `config` **must not** change. You can take a look at these values in the database by running the following SQL query:
 
 `sg=# select id, display_name, kind, config from external_services order by id;`