From a34e5743d66147f604cf886be34e62ad52e8db66 Mon Sep 17 00:00:00 2001 From: linfraze Date: Thu, 17 Apr 2025 13:47:55 -0400 Subject: [PATCH 1/2] RHIDP-6146: Create developer-focused TechDocs content --- assemblies/assembly-techdocs-add-docs.adoc | 8 ++++ assemblies/assembly-using-techdocs.adoc | 14 +++++++ .../proc-techdocs-add-doc-github.adoc | 29 +++++++++++++ modules/techdocs/proc-techdocs-edit-docs.adoc | 17 ++++++++ modules/techdocs/proc-techdocs-find-docs.adoc | 28 +++++++++++++ modules/techdocs/proc-techdocs-view-docs.adoc | 41 +++++++++++++++++++ titles/techdocs/master.adoc | 3 ++ 7 files changed, 140 insertions(+) create mode 100644 assemblies/assembly-techdocs-add-docs.adoc create mode 100644 assemblies/assembly-using-techdocs.adoc create mode 100644 modules/techdocs/proc-techdocs-add-doc-github.adoc create mode 100644 modules/techdocs/proc-techdocs-edit-docs.adoc create mode 100644 modules/techdocs/proc-techdocs-find-docs.adoc create mode 100644 modules/techdocs/proc-techdocs-view-docs.adoc diff --git a/assemblies/assembly-techdocs-add-docs.adoc b/assemblies/assembly-techdocs-add-docs.adoc new file mode 100644 index 0000000000..a64a1902ae --- /dev/null +++ b/assemblies/assembly-techdocs-add-docs.adoc @@ -0,0 +1,8 @@ +:_mod-docs-content-type: ASSEMBLY +:context: assembly-techdocs-add-docs +[id="{context}"] += Adding documentation to TechDocs + +After an administrator configures the TechDocs plugin, a developer can add documentation to TechDocs by importing it from a remote repository. Any authorized user or group can access the documentation that is imported into the TechDocs plugin. + +include::modules/techdocs/proc-techdocs-add-doc-github.adoc[] diff --git a/assemblies/assembly-using-techdocs.adoc b/assemblies/assembly-using-techdocs.adoc new file mode 100644 index 0000000000..d4356dc521 --- /dev/null +++ b/assemblies/assembly-using-techdocs.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: ASSEMBLY +:context: assembly-using-techdocs +[id="{context}"] += Using TechDocs + +The TechDocs plugin is installed and enabled on your {product} instance by default. After an administrator configures the TechDocs plugin, an authorized developer can use the TechDocs plugin to add, view, or manage documentation. + +include::assembly-techdocs-add-docs.adoc[leveloffset=+1] + +include::modules/techdocs/proc-techdocs-find-docs.adoc[] + +include::modules/techdocs/proc-techdocs-view-docs.adoc[] + +include::modules/techdocs/proc-techdocs-edit-docs.adoc[] diff --git a/modules/techdocs/proc-techdocs-add-doc-github.adoc b/modules/techdocs/proc-techdocs-add-doc-github.adoc new file mode 100644 index 0000000000..b203b1523c --- /dev/null +++ b/modules/techdocs/proc-techdocs-add-doc-github.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-add-docs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-add-docs-github_{context}"] +== Importing documentation into TechDocs from a remote repository + +Teams can store their documentation files in the same remote repository where they store their code files. You can import documentation into your TechDocs plugin from a GitHub repository that contains the documentation files that your team uses. + +.Prerequisites + +* Your organization has documentation stored in a GitHub repository. +* You have the `catalog.entity.create` and `catalog.location.create` permissions to import documentation into TechDocs from a remote repository. + +.Procedure + +. In your {product} instance, click *Catalog > Self-service > Register Existing Component*. +. In the *Select URL* box, enter the URL to the `catalog-info.yaml` file that you want to import from your repository using the following format: ++ +`https://github.com/__/__/blob/__/__/catalog-info.yaml` ++ +. Click *Analyze* +. Click *Finish* + +.Verification + +. In the {product} navigation menu, click *Docs*. +. Verify that the documentation that you imported is listed in the table on the Documentation page. diff --git a/modules/techdocs/proc-techdocs-edit-docs.adoc b/modules/techdocs/proc-techdocs-edit-docs.adoc new file mode 100644 index 0000000000..10a3e4838b --- /dev/null +++ b/modules/techdocs/proc-techdocs-edit-docs.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-using-techdocs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-edit-docs_{context}"] +== Editing documentation in TechDocs + +You can edit a document in your TechDocs plugin directly from the document book page. Any authorized user in your organization can edit a document regardless of whether or not they are the owner of the document. + +.Procedure + +. In the {product} navigation menu, click *Docs*. +. In the *Documentation* table, click the name of the document that you want to edit. +. In the document, click the *Edit this page* icon to open the document in your remote repository. +. In your remote repository, edit the document as needed. +. Use the repository provider UI and your usual team processes to commit and merge your changes. diff --git a/modules/techdocs/proc-techdocs-find-docs.adoc b/modules/techdocs/proc-techdocs-find-docs.adoc new file mode 100644 index 0000000000..c183af6d85 --- /dev/null +++ b/modules/techdocs/proc-techdocs-find-docs.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-using-techdocs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-find-docs_{context}"] +== Finding documentation in TechDocs + +By default, the TechDocs plugin *Documentation* page shows all of the documentation that your organization has imported into your {product} instance. You can use any combination of the following methods to find the documentation that you want to view: + +* Enter a keyword in the search bar to see all documents that contain the keyword anywhere in the document. +* Filter by *Owner* to see only documents that are owned by a particular user or group in your organization. +* Filter by *Tags* to see only documents that contain a particular tag. +* Filter by *Owned* to see only documents that are owned by you or by a group that you belong +* Filter by *Starred* to see only documents that you have added to favorites. + +By default, the *All* field shows the total number of documents that have been imported into TechDocs. If you search or use filters, the *All* field shows the number of documents that meet the search and filter criteria that you applied. + +.Prerequisites + +* The TechDocs plugin in enabled and configured +* Documentation is imported into TechDocs +* You have the required roles and permissions to add and view documentation to TechDocs + +.Procedure + +. In the {product} navigation menu, click *Docs*. +. On the *Documentation* page, use the search bar, filters, or both to locate the document that you want to view. diff --git a/modules/techdocs/proc-techdocs-view-docs.adoc b/modules/techdocs/proc-techdocs-view-docs.adoc new file mode 100644 index 0000000000..c34b824478 --- /dev/null +++ b/modules/techdocs/proc-techdocs-view-docs.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-using-techdocs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-view-docs_{context}"] +== Viewing documentation in TechDocs + +In TechDocs, a document might be part of a book that contains other documents that are related to the same topic. + +Clicking the name of a document in the table on the *Documentation* page opens the document in a book page. The name of the book is displayed on book the page. The book page contains the following elements: + +* The contents of the document. +* A search bar that you can use to search for keywords within the document. +* A navigation menu that you can use to navigate to other documents in the book. +* A *Table of contents* that you can use to navigate to other sections of the document. +* A *Next* button that you can use to navigate to the next sequential document in the book. + +You can use the elements on the book page to search, view, and navigate the documentation in the book. + +.Prerequisites + +* The TechDocs plugin in enabled and configured +* Documentation is imported into TechDocs +* You have the required roles and permissions to add and view documentation to TechDocs +* Optional: TechDocs add-ons are installed and configured + +.Procedure + +. In the {product} navigation menu, click *Docs*. +. In the *Documentation* table, click the name of the document that you want to view. +. On the book page, you can do any of the following optional actions: +* Use installed add-ons that extend the functionality of the default TechDocs plugin. +* Use the search bar to find keywords within the document. +* Use any of the following methods to navigate the documentation in the book: +** Use the *Table of contents* to navigate the any section of the document. +** Use the navigation menu to navigate to any document in the book. +** Click *Next* to navigate to the next sequential document in the book. + +.Additional resources +* xref:techdocs-addon[TechDocs add-ons] diff --git a/titles/techdocs/master.adoc b/titles/techdocs/master.adoc index cf9a0a8a03..a7cc3258be 100644 --- a/titles/techdocs/master.adoc +++ b/titles/techdocs/master.adoc @@ -10,6 +10,9 @@ include::modules/techdocs/con-techdocs-about.adoc[leveloffset=+1] // techdocs configuration include::assemblies/assembly-configuring-techdocs.adoc[leveloffset=+1] +// using techdocs +include::assemblies/assembly-using-techdocs.adoc[leveloffset=+1] + // techdocs add-ons include::assemblies/assembly-techdocs-addons.adoc[leveloffset=+1] From 0a7ae290817be4278a7c8834c9f89e19aafa785a Mon Sep 17 00:00:00 2001 From: linfraze Date: Tue, 22 Apr 2025 16:15:45 -0400 Subject: [PATCH 2/2] RHIDP-6146: Apply review comments --- assemblies/assembly-techdocs-add-docs.adoc | 2 +- assemblies/assembly-using-techdocs.adoc | 6 +++--- ...c => proc-techdocs-add-docs-from-remote-repo.adoc} | 11 ++++++----- modules/techdocs/proc-techdocs-edit-docs.adoc | 2 +- modules/techdocs/proc-techdocs-find-docs.adoc | 2 +- modules/techdocs/proc-techdocs-view-docs.adoc | 2 +- 6 files changed, 13 insertions(+), 12 deletions(-) rename modules/techdocs/{proc-techdocs-add-doc-github.adoc => proc-techdocs-add-docs-from-remote-repo.adoc} (73%) diff --git a/assemblies/assembly-techdocs-add-docs.adoc b/assemblies/assembly-techdocs-add-docs.adoc index a64a1902ae..ed5a306e10 100644 --- a/assemblies/assembly-techdocs-add-docs.adoc +++ b/assemblies/assembly-techdocs-add-docs.adoc @@ -5,4 +5,4 @@ After an administrator configures the TechDocs plugin, a developer can add documentation to TechDocs by importing it from a remote repository. Any authorized user or group can access the documentation that is imported into the TechDocs plugin. -include::modules/techdocs/proc-techdocs-add-doc-github.adoc[] +include::modules/techdocs/proc-techdocs-add-docs-from-remote-repo.adoc[leveloffset=+1] diff --git a/assemblies/assembly-using-techdocs.adoc b/assemblies/assembly-using-techdocs.adoc index d4356dc521..61990c879a 100644 --- a/assemblies/assembly-using-techdocs.adoc +++ b/assemblies/assembly-using-techdocs.adoc @@ -7,8 +7,8 @@ The TechDocs plugin is installed and enabled on your {product} instance by defau include::assembly-techdocs-add-docs.adoc[leveloffset=+1] -include::modules/techdocs/proc-techdocs-find-docs.adoc[] +include::modules/techdocs/proc-techdocs-find-docs.adoc[leveloffset=+1] -include::modules/techdocs/proc-techdocs-view-docs.adoc[] +include::modules/techdocs/proc-techdocs-view-docs.adoc[leveloffset=+1] -include::modules/techdocs/proc-techdocs-edit-docs.adoc[] +include::modules/techdocs/proc-techdocs-edit-docs.adoc[leveloffset=+1] diff --git a/modules/techdocs/proc-techdocs-add-doc-github.adoc b/modules/techdocs/proc-techdocs-add-docs-from-remote-repo.adoc similarity index 73% rename from modules/techdocs/proc-techdocs-add-doc-github.adoc rename to modules/techdocs/proc-techdocs-add-docs-from-remote-repo.adoc index b203b1523c..fd38baf500 100644 --- a/modules/techdocs/proc-techdocs-add-doc-github.adoc +++ b/modules/techdocs/proc-techdocs-add-docs-from-remote-repo.adoc @@ -3,14 +3,15 @@ // * assemblies/assembly-techdocs-add-docs.adoc :_mod-docs-content-type: PROCEDURE -[id="proc-techdocs-add-docs-github_{context}"] -== Importing documentation into TechDocs from a remote repository +[id="proc-techdocs-add-docs-from-remote-repo_{context}"] += Importing documentation into TechDocs from a remote repository -Teams can store their documentation files in the same remote repository where they store their code files. You can import documentation into your TechDocs plugin from a GitHub repository that contains the documentation files that your team uses. +Teams can store their documentation files in the same remote repository where they store their code files. You can import documentation into your TechDocs plugin from a remote repository that contains the documentation files that your team uses. .Prerequisites -* Your organization has documentation stored in a GitHub repository. +* Your organization has documentation files stored in a remote repository. +* You have a `mkdocs.yaml` file in the root directory of your repository. * You have the `catalog.entity.create` and `catalog.location.create` permissions to import documentation into TechDocs from a remote repository. .Procedure @@ -26,4 +27,4 @@ Teams can store their documentation files in the same remote repository where th .Verification . In the {product} navigation menu, click *Docs*. -. Verify that the documentation that you imported is listed in the table on the Documentation page. +. Verify that the documentation that you imported is listed in the table on the *Documentation* page. diff --git a/modules/techdocs/proc-techdocs-edit-docs.adoc b/modules/techdocs/proc-techdocs-edit-docs.adoc index 10a3e4838b..e93a38f03c 100644 --- a/modules/techdocs/proc-techdocs-edit-docs.adoc +++ b/modules/techdocs/proc-techdocs-edit-docs.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="proc-techdocs-edit-docs_{context}"] -== Editing documentation in TechDocs += Editing documentation in TechDocs You can edit a document in your TechDocs plugin directly from the document book page. Any authorized user in your organization can edit a document regardless of whether or not they are the owner of the document. diff --git a/modules/techdocs/proc-techdocs-find-docs.adoc b/modules/techdocs/proc-techdocs-find-docs.adoc index c183af6d85..56252f8c73 100644 --- a/modules/techdocs/proc-techdocs-find-docs.adoc +++ b/modules/techdocs/proc-techdocs-find-docs.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="proc-techdocs-find-docs_{context}"] -== Finding documentation in TechDocs += Finding documentation in TechDocs By default, the TechDocs plugin *Documentation* page shows all of the documentation that your organization has imported into your {product} instance. You can use any combination of the following methods to find the documentation that you want to view: diff --git a/modules/techdocs/proc-techdocs-view-docs.adoc b/modules/techdocs/proc-techdocs-view-docs.adoc index c34b824478..6ec272a148 100644 --- a/modules/techdocs/proc-techdocs-view-docs.adoc +++ b/modules/techdocs/proc-techdocs-view-docs.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="proc-techdocs-view-docs_{context}"] -== Viewing documentation in TechDocs += Viewing documentation in TechDocs In TechDocs, a document might be part of a book that contains other documents that are related to the same topic.