As a content provider/author for quick starts I would like a way to parameterize certain bits of text (e.g. the product name between community and product.

Note: cloud.redhat.com quick starts provide a default value, and then to override it in the product. We only have about a dozen parameters (e.g. product-short (name), product-long (name)) etc.

Requirements:

• Recommended solution should support screen reader users
• As a user, I want to easily see which step I am on out of the total number (progress indicator)
• If I have previously started a quick start and return to finish it at a later time, I want my progress to be saved and to easily see what I have previously completed

Proposed updates:

• When previous tasks are listed as completed, just the task label is included (and not additional text after the step).
• #53
  • NOTE that some concern was raised regarding whether the (!) icon should be red or not. Further discussion with designers might be needed.
• #54
• #55
• #57

Example of the current task with "2 of 3" in gray text:

Example of a skipped task:

Example of the current implementation:

Requirements:

• As a user, I want to be able to jump right into the next recommended quick start without having to return to the quick starts catalog
• The title of the quick start should be easy to scan and identify relative to the surrounding contents

Proposed updates:

• When recommending a next step, this can be anything (i.e. not just a quick start), and this can be between 0-3 items listed.
• For the hyperlink that points to the next quick start, visually offset (if possible) the title of the quick start from the remainder of the text. For example:

  Start the Monitor your sample application quick start.

Examples of current UI:

Add support for external content to be displayed inside the quick start drawer. This could be helpful in cases where instead of linking off to documentation you could insert that documentation directly into the quick start, etc. (Could be helpful for products like Managed Kafka)

We should investigate if there's any library changes needed for localization or if it's only up to the consumer to provide localized quick start content.

Add axe automated testing to our build and fix the following issues:

A script should be able to run that updates a quick starts prerequisites as the user completes them, giving users updated information about what they still have outstanding to complete before taking the current quick start. (Should be able to also run clean up script so the next person can run it again.)

This also brings up the question of how to handle quick starts that aren't available yet or when prerequisites haven't been completed. Are there any valid use cases for locking quick starts? Given that validation is still not possible, locking quick starts could just invite users to “fake” completion of a quick start to get to the next one. Additionally, we may not want to block advanced users from accessing a quick start later in a course if they don’t need the prior ones. If we find a valid use case for this, we could consider greying out and locking quick starts that users are not yet able to take. (Info on this pulled from OpenShift's Quick start courses exploration doc, page 7 and 8).

We're using some of the service icons multiple times on the quick start and documentation cards and this currently only supports base-64 formats. This format seems to cause some jagged edges with the icon.

This request is for:

1. Being able to support other image formats
2. Being able to optimize the page load by using CDN delivered images

cc: @pmuir @wtrocki

This collection of issues is a bunch of easy fixes that will help the screen reader experience quite a bit. Some of these are documentation/demo issues but are still important to show consumers the correct way to do it.

In our current implementation of the page, there's an issue with the CSS where the background color doesn't fill the page header section. I'm not able to reproduce this issue in the extension demo.

Is it possible to adjust the CSS to use padding instead of margin on the pfext-page-layout__title element, similar to how spacing is handled for page sections in PF? Or is it possible to use PF components for these page sections instead?

Fixes: https://issues.redhat.com/browse/MGDSTRM-4732

Set of PRs in this bundle:

#32
RedHatInsights/insights-chrome#1586
https://gitlab.cee.redhat.com/mk-ci-cd/application-services-ui/-/merge_requests/146
redhat-developer/app-services-guides#266

Quick start contents should support rendering an inline alert anywhere within the contents (e.g. within a numbered list), similar to the example shown here: https://access.redhat.com/documentation/en-us/red_hat_openshift_streams_for_apache_kafka/1/guide/f351c4bd-9840-42ef-bcf2-b0c9be4ee30a#_b4f95791-b992-429d-9e8e-cceb63ae829f

You used to be able to configure each task's summary, so that you could either show a success message, or a failure message, like Try the steps again.

It appears that now there is no success message shown, and on failure is hardcoded to Try the steps again.

The config looks like this

summary:
        success: You have learned about highlighting elements!
        failed: Try the steps again.

Also, if a task does not have the review/Check your work section, it still automatically counts as a failure and shows the Try the steps again. message. I wouldn't expect to see it.
A check your work section for reference:

review:
        instructions: |-
          - Did you complete the task successfully?
        failedTaskHelp: This task isn’t verified yet. Try the task again.

Thanks for the clarification!

In the case where the user selects no on CYW, I also think the (!) icon and text should be red. It is listed under proposed updates here. Should I go ahead and make that change (along with removing "Try the steps again")?

Yes, let's go with that. There was some feedback in a google doc comment, in favor of having the icon color in the task match the icon color in the CYW section, which makes sense.

There was also some concern raised about using red, but since that requires discussion with the larger design team, I would defer that to a separate issue to update both the icon color and CYW section at the same time. For now I've added an agenda item for the next meeting to discuss.

A remaining case which I am unclear on how to handle is the when the user visits the task, opens the CYW section, but makes no selection before moving on to the next task. (See task 2 from the example screenshot with Review task status.) Should "Try the steps again" be displayed? Should the icon change to (!) like step 3, and if so should we use a different color to indicate a difference in state from Visited task status like task 3?

There was a previous issue to have the CYW prompt always visible (i.e. not require the user to hit Next to see a CYW prompt): #3. This issue is closed, but when I look at the demo, I see the original behavior is still there. @jschuler Can you comment on this? Is that behavior configurable by the consumer?

To answer @CooperRedhat's question, if it is configurable that the CYW section is not always visible, then I would expect these two states to be displayed the same way—with a blue number and a "Try the steps again" statement. As an FYI, we want to review the current quick start behavior with usability testing, so it's possible there will be new insights to inform the design of this.

• 2: visited, CYW opened, no selection made.
  -- Review task status
• 3: visited, CYW never opened before continuing to next step.
  -- Will only happen when a user selects a later step from the intro page of the QS, because clicking next first opens CYW before moving to next step (which I THINK is what you mean by skipping a step)
  -- Visited task status

Originally posted by @jgiardino in #56 (comment)

Also in what cases should the restart button be shown on initial screen

Re: #29 / #57

PFReact issue to add this functionality: patternfly/patternfly-react#6361

Should there be the ability for Quick Starts to exist on its own separately and be able to follow you through different environments and windows? This would support learning paths across several products and enable users to move through different products that each have a quick start. This could be particularly beneficial to products like OpenShift that branch off into others. If the quick start from OpenShift goes to a specific product we can add some code to (for example to add information that you’re currently part of a learning path/tutorial), that would help.

This would also help support use cases where context could be lost. For example, if you click on step 2 and it goes somewhere else, you could lose the context of the quick starts you're in and the prerequisites you completed are now also lost.

A POC was created on this idea previously, and this doc describes this idea. However, the downside to working on this issue is that it would likely require lots of engineering resources to achieve.

Since @percy/script is now deprecated
See:
https://www.npmjs.com/package/@percy/script
https://docs.percy.io/docs/migrating-to-percy-cli

Found this when I was trying to update allQuickStarts in the context based on the chosen language. When I changed it didn't rerender. So I had to use QuickStartContainer.

@mceledonia

We need to finalize and provide updated designs for the Learning Path Details Pages. Brie had worked on these explorations in the past, but they're a bit outdated and need some refinement.

FYI @CooperRedhat @jessiehuff

Making note of this quick starts related issue from here so we can keep an eye on it
openshift/console#9723

QuickStartDrawer/catalog should be able to render without quick starts, and once the quick starts have been passed in should let them re-render.

#3 Asked for CYW to be optionally visible (i.e. configurable) but user feedback suggests it should always be there before clicking next.

This issue may be fixed after completing #29, but wanted to make sure this doesn't get lost.

Would help the user have a visual queue after pressing the Restart button on the initial task page.

And the need for apps to pull in import "@patternfly/quickstarts/dist/quickstarts-bootstrap.min.css";
Create new classes instead that should be bundled into the quickstarts.css.

Aside from usability issues, the double Next click could have a negative impact on usage metrics.

We should investigate if there is anything that we need to do in order to support dark theme with Quick Starts

openshift/console#9339

Main issue to track ongoing work with integrating quick starts into didact

Additional feature work

• ability to have multiple quick starts?
• register quick starts in the didact pane
• open didact in side window

Additional items:

• create a real use-case scenario/example (quarkus + getting started)
• user testing?

Note: These are visual breaking changes and should be included in a new version release. Design leads should communicate these proposed updates with their product team leads (fyi @kywalker-rh @bmignano).

Currently, the quick start drawer uses the same visual styling as a PF drawer. Given that the quick start drawer can display next to another drawer that is part of the application UI, there isn't much visual differentiation between the two drawers which makes it challenging to identify what part of the UI is from the app and what part is from the quick start.

Proposed updates are captured here: https://marvelapp.com/prototype/cdb107d/screen/80786868

Currently, "Restart" only displays in the last screen of the drawer. (see example below)

This task is to always display a Restart action in the footer.

During a design review, we discussed only showing "Restart" in the card if the quick start was completed. This means that a quick start in progress would only display the action "Continue". With this action being removed from the card for quick starts that are in progress, having an easy way to jump to the intro screen would be helpful.

cc'ing @bmignano

Classes should not begin with .co-* or .ocs-* as those come from OpenShift. Use a new prefix instead.

When moving from a task step to another step, the top should be visible

For example by adding comments to
https://github.com/patternfly/patternfly-quickstarts/blob/main/packages/module/src/utils/quick-start-types.ts

see changes made in #67.
there should be a transpilation pipeline to use TSX content as commonJS in a webpack node process.

also look into creating a module or bundling it into the main quick starts library, so that asciidoc consumers can more easily get these new capabilities

See cloudmosaic/quickstarts#44

Whenever a keyboard or screen reader user is moving through a quick start, if they click on a footer action like Next, Back, or Restart, their focus stays on the button, forcing them to go backwards to get to the top of the quick start. Focus should instead shift to the top of the quick start if they're pressing the footer actions.

I think it's fair to assume that if a user is moving through a quick start, they should be following the steps and tasks in the quick start. Perhaps some users may want to quickly click through the footer actions, but I imagine that they may skip actions if they did this. Also, we recently added an auto scroll for mouse users to take them to the top of the content so I think it would make sense to have parity for keyboard and screen reader users.

When a user is tabbing through the page, the user should be able to focus on a quick starts card, select it by pressing Enter, and then focus should shift to the Quick Start. (Doing this for keyboard users should likewise translate over to screen reader interaction.)

We show an example of something like this in PF cards here for example.

It would make sense to explore how we can order and group quick starts into different potential learning paths. For example, three quick starts could make up a course and create structured groupings. (Would be interesting to explore how we can create loose groupings as well.)

There was an OpenShift issue opened on this as well.

Some exploration has been done on this topic in this doc.

From #50:

• This (App-level preference) would be useful to expose on the demo app though, would be nice to change some settings on the fly to play and test the options. Perhaps a button in the demo header that when pressed could give you a preferences modal to set the current language, and this new setting, to start (and remove the Home route and page.

We need a few updates to allow for localization:

• Need a language key (should this be optional and have fallback be browser default language?)
• Need optional country code
• Need QS to default to the language code if the country code isn't available

Currently, prerequisites are not shown in the quick starts drawer. Here are the proposed designs for adding in prerequisites to the quick starts intro, as well as additional task-level prerequisites: https://marvelapp.com/prototype/15agb91j

User Story
As a quick start user, when I'm viewing contents of a quick start, I want know what prerequisites exist so that can make sure I'm not trying to complete a quick start before I'm ready.

Requirements

• Prerequisites should be easily visible and accessible from the drawer
• Can be hidden easily if it ends up taking up too much space or away from the context of the intro.
• Users should confirm that they meet the prereqs, esp if not having them in place could break the quick start experience.
• For an individual task (i.e. not intro or conclusion) — If we incorporate a Prerequisites heading, also incorporate a Procedure heading, to be consistent with our quick start presentation on the Customer Portal.
• Include the ability to show prerequisites for the entire quick start in the intro as well as per task. Assumption is that prerequisites captured in individual tasks would capture things they’ve completed in a previous task.
• Innovation - Preqs are automatically checked/verified by the system where possible
• For this design task - how would checked/verified items display

One of the findings identified during a user review related to quick starts was that prerequisites should be communicated in the drawer.

The design task for this update is captured in https://issues.redhat.com/browse/APPDUX-1089
cc @lboehling