diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 743be078457a..89f20513d54c 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -898,10 +898,14 @@ Topics: File: uninstalling-web-terminal - Name: Disabling the web console File: disabling-web-console +Name: Quick starts + Dir: quick-starts Distros: openshift-enterprise,openshift-origin -- Name: Creating quick start tutorials - File: creating-quick-start-tutorials - Distros: openshift-enterprise,openshift-origin + Topics: + - Name: Quick start tutorials in the web console + File: quick-starts-web-console + Name: Creating quick start tutorials + File: creating-quick-start-tutorials - Name: Optional capabilities and products File: capabilities_products-web-console Distros: openshift-enterprise,openshift-origin diff --git a/modules/accessing-quick-starts.adoc b/modules/accessing-quick-starts.adoc new file mode 100644 index 000000000000..2f7e0a7f8c0b --- /dev/null +++ b/modules/accessing-quick-starts.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * web_console/about-quick-start-tutorials.adoc + +:_mod-docs-content-type: PROCEDURE +[id="accessing-quick-starts_{context}"] += Accessing quick starts + +You can access quick starts under the *Getting started resources* pane on the *Overview* page of the web console. + +.Prerequisites +* You have access to a {product-title} cluster with `cluster-admin` privledges. [Need to check and see if it is in dev console too] +. In the *Administrator* or *Developer* perspective, click the *Help icon* and select *Quick Starts*. (need to verify if this is in this location too) +.Procedure + +. Log into the {product-title} web console using your credintials. + +. There are two ways you can acccess quick start tutorials: +.. On the *Cluster Overview* page, navigate to the *Getting started resources* section and click *View all quick starts* under *Build with guided documentation*. +.. In the *Administrator* or *Developer* perspective, click the *Help icon* and select *Quick Starts*. + +. Once you are on the *Quick Starts* page, click a quick start card with the topic you would like step-by-step instructions and tasks for. + +. In the panel that appears, click *Start*. + +. Complete the on-screen instructions, then click *Next*. + +. In the *Check your work* module that appears, answer the question to confirm that you successfully completed the task. +.. If you select *Yes*, click *Next* to continue to the next task. +.. If you select *No*, repeat the task instructions and check your work again. + +. After completing the final task, click *Close* to close the quick start. \ No newline at end of file diff --git a/modules/quick-start-components.adoc b/modules/quick-start-components.adoc deleted file mode 100644 index 4d34ee2e17cf..000000000000 --- a/modules/quick-start-components.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="quick-start-components_{context}"] -= Quick start components - -A quick start consists of the following sections: - -* *Card*: The catalog tile that provides the basic information of the quick start, including title, description, time commitment, and completion status -* *Introduction*: A brief overview of the goal and tasks of the quick start -* *Task headings*: Hyper-linked titles for each task in the quick start -* *Check your work module*: A module for a user to confirm that they completed a task successfully before advancing to the next task in the quick start -* *Hints*: An animation to help users identify specific areas of the product -* *Buttons* -** *Next and back buttons*: Buttons for navigating the steps and modules within each task of a quick start -** *Final screen buttons*: Buttons for closing the quick start, going back to previous tasks within the quick start, and viewing all quick starts - -The main content area of a quick start includes the following sections: - -* *Card copy* -* *Introduction* -* *Task steps* -* *Modals and in-app messaging* -* *Check your work module* diff --git a/modules/quick-start-user-workflow.adoc b/modules/quick-start-user-workflow.adoc deleted file mode 100644 index 47c2a19ad13b..000000000000 --- a/modules/quick-start-user-workflow.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="quick-start-user-workflow_{context}"] -= Quick start user workflow - -When you interact with an existing quick start tutorial, this is the expected workflow experience: - -. In the *Administrator* or *Developer* perspective, click the *Help icon* and select *Quick Starts*. - -. Click a quick start card. - -. In the panel that appears, click *Start*. - -. Complete the on-screen instructions, then click *Next*. - -. In the *Check your work* module that appears, answer the question to confirm that you successfully completed the task. -.. If you select *Yes*, click *Next* to continue to the next task. -.. If you select *No*, repeat the task instructions and check your work again. - -. Repeat steps 1 through 6 above to complete the remaining tasks in the quick start. -. After completing the final task, click *Close* to close the quick start. diff --git a/modules/quick-starts-accessing-and-executing-code-snippets.adoc b/modules/quick-starts-accessing-and-executing-code-snippets.adoc index a30861e9741d..fe42e86f0658 100644 --- a/modules/quick-starts-accessing-and-executing-code-snippets.adoc +++ b/modules/quick-starts-accessing-and-executing-code-snippets.adoc @@ -2,27 +2,28 @@ // // * web_console/creating-quick-start-tutorials.adoc +:_mod-docs-content-type: PROCEDURE [id="quick-starts-accessing-and-executing-code-snippets_{context}"] -= Code snippet markdown reference += Code snippet markdown syntax -You can execute a CLI code snippet when it is included in a quick start from the web console. To use this feature, you must first install the Web Terminal Operator. The web terminal and code snippet actions that execute in the web terminal are not present if you do not install the Web Terminal Operator. Alternatively, you can copy a code snippet to the clipboard regardless of whether you have the Web Terminal Operator installed or not. +You can execute a CLI code snippet when it is included in a quick start from the web console. -[id="quick-starts-syntax-for-inline-code-snippets_{context}"] -== Syntax for inline code snippets +.Prerequisites +* You have access to a {product-title} cluster with `cluster-admin` privledges. +.Procedure + +. Copy an in-line or multi-line code snippet to the clipboard. + +.. Syntax for inline code snippets ++ ---- `code block`{{copy}} `code block`{{execute}} ---- -[NOTE] -==== -If the `execute` syntax is used, the *Copy to clipboard* action is present whether you have the Web Terminal Operator installed or not. -==== - -[id="quick-starts-syntax-for-multi-line-code-snippets_{context}"] -== Syntax for multi-line code snippets - +.. Syntax for multi-line code snippets ++ ---- ``` multi line code block @@ -32,3 +33,7 @@ multi line code block multi line code block ```{{execute}} ---- + +. Optional: Install the Web Terminal Operator. + + diff --git a/modules/quick-starts-supported-tags.adoc b/modules/quick-starts-supported-tags.adoc deleted file mode 100644 index df4274dfd136..000000000000 --- a/modules/quick-starts-supported-tags.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="supported-tags-for-quick-starts_{context}"] -= Supported tags for quick starts - -Write your quick start content in markdown using these tags. The markdown is converted to HTML. - -[cols="2",options="header"] -|=== -|Tag -|Description - -|`'b',` -|Defines bold text. - -|`'img',` -|Embeds an image. - -|`'i',` -|Defines italic text. - -|`'strike',` -|Defines strike-through text. - -|`'s',` -|Defines smaller text - -|`'del',` -|Defines smaller text. - -|`'em',` -|Defines emphasized text. - -|`'strong',` -|Defines important text. - -|`'a',` -|Defines an anchor tag. - -|`'p',` -|Defines paragraph text. - -|`'h1',` -|Defines a level 1 heading. - -|`'h2',` -|Defines a level 2 heading. - -|`'h3',` -|Defines a level 3 heading. - -|`'h4',` -|Defines a level 4 heading. - -|`'ul',` -|Defines an unordered list. - -|`'ol',` -|Defines an ordered list. - -|`'li',` -|Defines a list item. - -|`'code',` -|Defines a text as code. - -|`'pre',` -|Defines a block of preformatted text. - -|`'button',` -|Defines a button in text. -|=== diff --git a/modules/understanding-quick-starts.adoc b/modules/understanding-quick-starts.adoc deleted file mode 100644 index 3f1887d387c3..000000000000 --- a/modules/understanding-quick-starts.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -:_mod-docs-content-type: CONCEPT -[id="understanding-quick-starts_{context}"] -= Understanding quick starts - -A quick start is a guided tutorial with user tasks. In the web console, you can access quick starts under the *Help* menu. They are especially useful for getting oriented with an application, Operator, or other product offering. - -A quick start primarily consists of tasks and steps. Each task has multiple steps, and each quick start has multiple tasks. For example: - -* Task 1 -** Step 1 -** Step 2 -** Step 3 -* Task 2 -** Step 1 -** Step 2 -** Step 3 -* Task 3 -** Step 1 -** Step 2 -** Step 3 diff --git a/web_console/quick-starts/_attributes b/web_console/quick-starts/_attributes new file mode 120000 index 000000000000..f27fd275ea6b --- /dev/null +++ b/web_console/quick-starts/_attributes @@ -0,0 +1 @@ +../_attributes/ \ No newline at end of file diff --git a/web_console/creating-quick-start-tutorials.adoc b/web_console/quick-starts/creating-quick-start-tutorials.adoc similarity index 86% rename from web_console/creating-quick-start-tutorials.adoc rename to web_console/quick-starts/creating-quick-start-tutorials.adoc index d5fb364ff7de..2879b6168a9f 100644 --- a/web_console/creating-quick-start-tutorials.adoc +++ b/web_console/quick-starts/creating-quick-start-tutorials.adoc @@ -17,13 +17,7 @@ toc::[] If you are creating quick start tutorials for the {product-title} web console, follow these guidelines to maintain a consistent user experience across all quick starts. -include::modules/understanding-quick-starts.adoc[leveloffset=+1] - -include::modules/quick-start-user-workflow.adoc[leveloffset=+1] - -include::modules/quick-start-components.adoc[leveloffset=+1] - -// Hiding in ROSA/OSD, as dedicated-admins cannot create "consolequickstarts" resource +// Hiding in ROSA/OSD, as dedicated-admins cannot create "consolequickstarts" resource ifndef::openshift-rosa,openshift-dedicated[] include::modules/contributing-quick-starts.adoc[leveloffset=+1] @@ -35,12 +29,16 @@ include::modules/quick-start-limiting-access.adoc[leveloffset=+2] include::modules/quick-starts-linking-to-others.adoc[leveloffset=+2] -include::modules/quick-starts-supported-tags.adoc[leveloffset=+2] - include::modules/quick-starts-highlighting-reference.adoc[leveloffset=+2] include::modules/quick-starts-accessing-and-executing-code-snippets.adoc[leveloffset=+2] +//[id="quick-start-code-snippet-additional-resources"] +//[role="_additional-resources"] +//== Additional resources + +//* xref:../web terminal operator + include::modules/quick-start-content-guidelines.adoc[leveloffset=+1] [id="quick-start-tutorials-additional-resources"] @@ -50,3 +48,4 @@ include::modules/quick-start-content-guidelines.adoc[leveloffset=+1] * For voice and tone requirements, refer to link:https://www.patternfly.org/v4/ux-writing/brand-voice-and-tone[PatternFly's brand voice and tone guidelines]. * For other UX content guidance, refer to all areas of link:https://www.patternfly.org/v4/ux-writing/about[PatternFly's UX writing style guide]. endif::openshift-rosa,openshift-dedicated[] +* For a cheat sheet of supported markdown tags, refer to link:https://www.markdownguide.org/cheat-sheet/[Markdwon Cheat Sheet]. diff --git a/web_console/quick-starts/images b/web_console/quick-starts/images new file mode 120000 index 000000000000..e4c5bd02a10a --- /dev/null +++ b/web_console/quick-starts/images @@ -0,0 +1 @@ +../images/ \ No newline at end of file diff --git a/web_console/quick-starts/modules b/web_console/quick-starts/modules new file mode 120000 index 000000000000..43aab75b53c9 --- /dev/null +++ b/web_console/quick-starts/modules @@ -0,0 +1 @@ +../modules/ \ No newline at end of file diff --git a/web_console/quick-starts/quick-starts-web-console.adoc b/web_console/quick-starts/quick-starts-web-console.adoc new file mode 100644 index 000000000000..e297a4d59d16 --- /dev/null +++ b/web_console/quick-starts/quick-starts-web-console.adoc @@ -0,0 +1,13 @@ +:_mod-docs-content-type: ASSEMBLY +[id="creating-quick-start-tutorials"] += Quick start tutorials in the web console +include::_attributes/common-attributes.adoc[] +:context: quick-start-tutorials + +toc::[] + +A quick start is a guided tutorial with user tasks in the {product-title} web console. With quick starts, you can get oriented with an application, Operator, or other product offering. + +A quick start primarily consists of tasks and steps. Each task has multiple steps, and each quick start has multiple tasks. + +include::modules/accessing-quick-starts.adoc[leveloffset=+1] \ No newline at end of file diff --git a/web_console/quick-starts/snippets b/web_console/quick-starts/snippets new file mode 120000 index 000000000000..9f5bc7e4dde0 --- /dev/null +++ b/web_console/quick-starts/snippets @@ -0,0 +1 @@ +../snippets \ No newline at end of file