Add latest changes from gitlab-org/gitlab@master

1 files changed, 15 insertions, 6 deletions

diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md
index af24fbe303b..2fe4494bc37 100644
--- a/doc/development/documentation/site_architecture/index.md
+++ b/doc/development/documentation/site_architecture/index.md
@@ -64,13 +64,22 @@ Learn more about [the docs folder structure](folder_structure.md).
 If you have code and documentation in a repository other than the [primary repositories](#architecture),
 you should keep the documentation with the code in that repository.
 
-Then you can either:
-
-- [Add the repository to the list of products](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/development.md#add-a-new-product)
-  published at <https://docs.gitlab.com>.
-- [Add an entry in the global navigation](global_nav.md#add-a-navigation-entry) for
-  <https://docs.gitlab.com> that links to the documentation in that repository.
+Then you can use one of these approaches:
+
+- (Recommended) [Add the repository to the list of products](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/development.md#add-a-new-product)
+  published at <https://docs.gitlab.com>. The source of the documentation pages remains
+  in the external repository, but the resulting pages are indexed and searchable on <https://docs.gitlab.com>.
+- (Recommended) [Add an entry in the global navigation](global_nav.md#add-a-navigation-entry) for
+  <https://docs.gitlab.com> that links directly to the documentation in that external repository.
+  The documentation pages are not indexed or searchable on <https://docs.gitlab.com>.
   View [an example](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fedb6378a3c92274ba3b6031df0d34455594e4cc/content/_data/navigation.yaml#L2944-L2946).
+- Create a landing page for the product in the `gitlab` repository, and add the landing page
+  [to the global navigation](global_nav.md#add-a-navigation-entry), but keep the rest
+  of the documentation in the external repository. The landing page is indexed and
+  searchable on <https://docs.gitlab.com>, but the rest of the documentation is not.
+  For example, the [GitLab Workflow extension for VS Code](../../../user/project/repository/vscode.md).
+  We do not encourage the use of [pages with lists of links](../structure.md#topics-and-resources-pages),
+  so only use this option if the recommended options are not feasible.
 
 ## Assets