rht-labs/tech-exercise

[enhancement] - Numerical Ordering of The Instruction Site

mtakane opened this issue · 4 comments

mtakane commented

📝 Description

Difficulty in determining where a person is when asking for help about a specific step. Want people to be able to specifically call out where they are in the exercises without needing to know or remember which "Here be Dragons" a person is referring to or where "Get GitLab Ready for GitOps" lives.

I do agree that they could just use the search bar, but two folks during run-throughs had trouble describing where they were in the exercise and seasoned facilitators had trouble knowing exactly where in the instructions people were.

🚶 Steps to reproduce

go to the instruction site with the left pane open

🧙‍♀️ Suggested solution

Look at adopting a numbering structure to better indicate where in the instructions you are.
example:

  1. The Manual Menace
    1.1 The Basics
    1.2 ArgoCD
    1.3 Ubiquitous Journey
    1.3.1 Get GitLab Ready for GitOps
    1.3.2 Deploy Ubiquitous Journey
paulbarfuss commented

This looks great to me. I agree this would help students and facilitators be able to communicate better about issues that come up during a session.

It would also enable being able to easily link to other sections of the exercises to not have to duplicate instructions.

eformat commented

@mtakane @paulbarfuss - not sure this is a BUG per se ;)

Apart from the search .. if you select the section title in the markdown and right click - copy url:

https://rht-labs.com/tech-exercise/#/3-revenge-of-the-automated-testing/7b-tekton?id=check-builddeploy-time-violations

you get the exact section you are in. all the steps within sections are numbered already.

is that not enough ? you can just share the URL with others / in the chat or wherever if you are stuck

pretty arduous to goto the depths of 1.3.2.3 .. stuff IMHO

paulbarfuss commented

Here is another example of why it is a bit confusing with the current numbering:

Student: I am getting an error setting the team name on step 2 of the Ubiquitous Journey section.

Instructor: Taking a look at step 2 now. What is the error you are getting? Is it when you are clicking "Create Project"?

Student: Where is the "Create Project" button.

Instructor: Big green button. Please share your screen.

Student shares CodeReady Workspaces values-tooling.yaml

Instructor: And you said you are on Step 2 of Ubiquitous Journey? Let's see your Gitlab "Create Project" tab.

Student: Oh, I already did that up above on... looks like Step 2 of Ubiquitous Journey. Why are there two steps with the same number?

Instructor: ... 🤦‍♂️

Going 4 levels deep does seem a little heavy but this is actually how the exercises are structured:

Exercise.Section.Subsection.Step

The main issues are:

  • No numbering at the 3rd level (subsection?)
  • Numbering repeats with each new subsection at the 4th level (steps)
eformat commented

LOLZ, nice explanation.
i guess technically .. there is a reason why it repeats - which is Markdown automatic numbering for ordered lists. We use this a lot.

what you are suggesting is numbering the headings in markdown - which can be done by adding custom html to all the markdown docs. and then, NOT using markdown automatic numbering in the sections, so it doesn't repeat - again probably custom html. which is quite a lot of work i think.

perhaps we wait, until its facilitated in real life, to see if this is worth doing and if its a problem that eventuates.

you can always just use WORDS for the Subsection today

Instructor: are you in the "Get GitLab Ready for GitOps" or the "Deploy Ubiquitous Journey 🔥🦄" section ?