Back to Designs page

Table of Contents

Related Research

No research entries have been linked to this design.

Additional tags

# learn 6

Learning resources

Design type: Quick starts | Product area: Hybrid Cloud Console
Mary Shakshober avatar

Author: Mary Shakshober
Last edit: May 31, 2023

Creating and maintaining Learning Resources pages using the GitHub UI

If you’d rather use the CLI, refer to this documentation here

Video demo of going through initial setup and adding new cards:


Designing a learning resources page in Sketch

Step 1: Add the Console Dot design kit to your Sketch library

Step 2: Open the Sketch UI, then add the Learning Resources template page.

[ + ] > Templates > ConsoleDot-DesignTemplate > Learning Resources page

Step 3: All Learning Resource pages should have all 4 content type areas displayed.

  1. Documentation
  2. Quick starts
  3. Learning paths
  4. Other content types

Step 4: Start adding cards based on what content type they are. If a given section does not have any cards that live inside it, the section should default to being collapsed. If there are cards in a given section, it should default to being expanded.


Your first contribution

Do this once to set up your local fork.

Step 1: Log into your GitHub account.

Step 2: Browse to the Insights Quickstarts repo. Doesn’t matter if you’re OpenShift, Anisble, or any other product -- this is where you will add ANY learning resources (even if it’s not a Quickstart).

Step 3: Click ‘Fork’ > ‘Create a new fork

Step 4: Make sure you have your personal GitHub account selected in the dropdown (if I didn’t already have an existing fork, I would select ‘maryshak1996’

Step 5: Click ‘Create fork’. 

You don’t need to do this ever again -- one and done baby!


For new cards you want to add

Create a folder for your learning source

Step 1: Find your fork of the Insights Quickstarts repo by browsing to the ‘Forks’ page in the repo. Find your account and click on the word ‘quickstarts’ next to your name. 

Step 2: Now that you’re in your fork, Click ‘Docs’ > ‘Quickstarts’.

Step 3: Click ‘Add file’ > ‘Create new file

Step 4: Make a folder by typing <bundlename-resource-name>/ (should automatically create a new folder). Don’t click ‘Enter’. 

Note: Replace <bundle-resource-name> with the filename for your quickstart, using the name of the bundle and a description of the content (like insights-configuring-access, or edge-manage-systems). Refer to the existing filenames for ideas.

Create the main yml file in that folder

Step 1: You should see that a directory was added to the breadcrumb string, and now you have another naming slot. (Fig. 4)

Step 2: Name the file the same name as your folder, ie. ‘<bundlename-resource-name>.yml

Step 3: Paste this code into the code editor. 

 apiVersion: console.openshift.io/v1
kind: QuickStarts
metadata:
 name: bundlename-resource-name
 externalDocumentation: true
spec:
 version: 0.1
 type:
   text: Content type
   color: color
 displayName: Title of Learning Resource
 icon: 
 description: Description of learning resource goes here and will get truncated automatically through css.
 link:
   href: URL to open in new tab
   text: Short action for a screen reader to announce

Step 4: Edit the fields accordingly

For ‘type:’ choose one of the following text/color pairs below” …

text: Quick start
color: green
text: Documentation
color: orange
text: Learning path
color: cyan
text: Other resources
color: purple 

See this guide to editing learning resources YML

You can also use the YML preview tool created by the console ENG team

Step 5: Click ‘Commit changes …

Step 6: Add more detail if needed

Step 7: Select ‘Create a new branch … start a pull request’.

Step 8: Click ‘Commit changes’.

Create the metadata.yml file

Step 1: Navigate to the folder you made (which now has the above yml file): bundlename-resource-name

Step 2: Once in there, click ‘Add file’ > ’Create new file

Step 3: Since you already have the folder created, just type ‘metadata.yml’ into the name field

Step 4: Paste this code into the code editor:

kind: QuickStarts # kind must always be “QuickStarts”
name: bundlename-resource-name
tags: # If you want to use more granular filtering add tags to the quickstart
 - kind: bundle

Step 5: Edit these fields:

name: bundlename-resource-name
value: [select from the second column in the table below]
BundleValue tag
Application & Data Servicesapplication-services
OpenShiftOpenShift
Ansible Automation Platformansible
Red Hat Insightsinsights
Edge Managementedge
Homelanding
All Servicesallservices
Identity & Access Managementiam
Internalinternal
Settingssettings


Step 6: Click ‘Commit changes …

Step 7: Add more detail if neeed

Step 8: Select ‘Create a new branch … start a pull request’.

Step 9: Click ‘Commit changes’.

Step 10: Navigate to the folder you made (which now has the above yml file): bundlename-resource-name

Step 11: It may take a minute or two to update, but you should shortly see two items in the folder

  1. Bundlename-resource-name.yml
  2. metadata.yml

Create the pull request

Step 1: Once they are both in there, click ‘Contribute’ > ‘Open pull request

Step 2: Click ‘View pull request

Step 3: Add a short description of what you need to happen (ie. Add [name of learning resource] to these bundles]

Step 4: From here, ENG will approve the PR and merge it! 


For editing existing cards

Step 1: Find your fork of the Insights Quickstarts repo by browsing to the ‘Forks’ page in the repo. Find your account and click on the word ‘quickstarts’ next to your name. 

Step 2: Now that you’re in your fork, Click ‘Docs’ > ‘Quickstarts

Step 3: Find the folder for the learning resource card you are looking for in the list view. Click on the title. 

Step 4: Click into the content yml file.

Step 5: Click the ‘Edit’ pencil in the top right toolbar.

Step 6: Make your changes in the YML code, then click ‘Commit changes…

Step 7: Create a PR requesting that the changes made to your fork be merged into main. Follow the instructions for ‘Create the pull request’ to do this part of the process.