Merge pull request #9586 from backstage/timbonicus/demphasize-replacement

De-emphasize replaceProcessors in GitHub org doc

docs/integrations/github/org.md

@@ -22,19 +22,6 @@ entities that mirror your org setup.
 The processor that performs the import, `GithubOrgReaderProcessor`, comes
 installed with the default setup of Backstage.
 
-If you have _replaced_ the set of processors in your installation using
-`replaceProcessors`, you can import and add it as follows:
-
-```ts
-// Typically in packages/backend/src/plugins/catalog.ts
-import { GithubOrgReaderProcessor } from '@backstage/plugin-catalog-backend';
-
-builder.replaceProcessors(
-  GithubOrgReaderProcessor.fromConfig(config, { logger }),
-  // ...
-);
-```
-
 ## Configuration
 
 The following configuration enables an import of the teams and users under the
@@ -51,10 +38,12 @@ If Backstage is configured to use GitHub Apps authentication you must grant
 `Read-Only` access for `Members` under `Organization` in order to ingest users
 correctly. You can modify the app's permissions under the organization settings,
 `https://github.com/organizations/{ORG}/settings/apps/{APP_NAME}/permissions`.
+
 ![permissions](../../assets/integrations/github/permissions.png)
 
 **Please note that when you change permissions, the app owner will get an email
 that must be approved first before the changes are applied.**
+
 ![email](../../assets/integrations/github/email.png)
 
 Locations point out the specific org(s) you want to import. The `type` of these
@@ -65,3 +54,22 @@ The authorization for loading org information comes from a configured
 [GitHub integration](locations.md#configuration). When using a personal access
 token, the token needs to have at least the scopes `read:org`, `read:user`, and
 `user:email` in the given `target`.
+
+## Addendum
+
+Some Backstage apps have _replaced_ the catalog processors to override the
+default catalog processing behavior. These apps will already have a call to
+`replaceProcessors` in the catalog initialization.
+
+In the unlikely scenario that this applies to your app, you can import and
+add the `GithubOrgReaderProcessor` as follows:
+
+```ts
+// Typically in packages/backend/src/plugins/catalog.ts
+import { GithubOrgReaderProcessor } from '@backstage/plugin-catalog-backend';
+
+builder.replaceProcessors(
+  // ... other processor replacements
+  GithubOrgReaderProcessor.fromConfig(config, { logger }),
+);
+```