Define next iteration of training content

[nrichers]

Internal Notes for Reviewers

This PR adds more content to our training portal. LIVE PREVIEW

Landing page changes

New section about the training program

Includes:

• Program overview
• Learning paths
• Sample training plan
• Training FAQs

Relocated video playlists

• Removed from the "Guides" landing page where they don't quite fit in and will be replaced by a new QuickStart experience

Before	After

Training program

Program overview

Adds a short, public-facing prospectus that accompanies our internal training playbook with new sidebar navigation:

Learning paths

Includes our full curriculum for the different courses in one place.

Note:

• Details about our planned content updates have been hidden from the output — refer to epic 8078 for details (or look in the source).
• Related, there is a mismatch between these learnings paths and what's currently in the available courses: sc-8501 will single-source the course cards.

Sample training plan

Similar to our internal training playbook, this page provides a sample of what is available through our training program on request:

Where do I find ...?

Training FAQs that map actual customer questions we have been asked to training and docs.

Notes

• This page introduces a new {.button-small} that can be used for inline links where margin links are cumbersome.
• The style mimics some of the features of our other FAQs and includes the same boilerplate text at the bottom but omits some of the visual cues to keep the style simple

External Release Notes

We’ve added a training overview, learning paths, and a sample training plan to help customers navigate their training journey. We’ve also introduced an FAQ that maps common customer questions to relevant learning paths.

Training portal{.button}

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[validbeck]

Learn with confidence

• FYI, we have to be careful about using the images in the headings when we have the ToC active:

  

  It works on the main landing page because we don't have the inline ToC active, but not so much in these other pages. Compromise?

  

• According to our file naming conventions, the program/overview.qmd should actually be program/program-overview.qmd to minimize conflicts with our OTHER main file named overview.qmd...

  • I think we shouldn't be naming files ANYTHING overview personally and instead just using the page title but we've already done it and it was in the original internal style guide so y'know 💀

• For someone who always harps on visual clutter, there sure is a lot of it on this overview page. Why are we using the .highlights class here randomly in the MIDDLE of the page? I've removed it as that looks better to me. "You have options" is... also oddly ominous. How about:

  

• Conversely, I think we do want to draw attention to the CTA at the bottom, so how about:

  

Learning paths

• The coming soon callouts were a bit intrusive, highlighting information that was a placeholder. How about:

  

  This also has the benefit of showing up in the ToC, giving users a heads-up instead of disappointment:

  

• I feel like a lot of attention is being given to the module #s when they shouldn't be the focus. I tried instead:

  

Where do I find ...?

• Ellipses should have a space before and after, as they are treated as a word in formatting.

• The original button-small really doesn't work for me as the font is illegible, but I see why you tried them out to reduce the amount of spacing there needs to be between lines. I would rather have more white-space than unreadable buttons and honestly the lack of vertical spacing between the lines of buttons is oof for parsing.

  I'm thinking the ASCII arrows might not render the same on everyone's machines/browsers either. When we use smallcaps generally we don't capitalize the first letter either, since that looks off.

  How about:

  

  FUTURE FOOD FOR THOUGHT: Also.... this layout isn't realllllyyyyy mobile responsive:

  

  The fact that we have to use a separate flexbox for each question is an authoring nightmare. Perhaps a use case for our new filtered tables if the layout is gonna be wonky anwyay?

General notes

• I noticed you removed the BG colour from the sidebar since our topnav is now that colour for training, but now it looks kind of off/blends in too much to me. Also, you removed it for ALL pages in the site AND the ToC section (you thought you could sneak that by me, huh? After we had a month long argument about the sidebar/ToC BG? Nice try!) — I don't agree with this change as I preferred the version with SOME contrast and that was the one we previously agreed upon. Can we compromise, add it back to the rest of the site where training isn't involved?
• For training, let's keep the lack of BG colour, but I've changed the colour of the border just slightly for visual distinction:

• Overall, I like the restructure/outline given by this new content a lot! It introduces what our training has to offer and gives users some better direction. 🎉

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[nrichers]

• I noticed you removed the BG colour from the sidebar since our topnav is now that colour for training, but now it looks kind of off/blends in too much to me. Also, you removed it for ALL pages in the site AND the ToC section (you thought you could sneak that by me, huh? After we had a month long argument about the sidebar/ToC BG? Nice try!) — I don't agree with this change as I preferred the version with SOME contrast and that was the one we previously agreed upon. Can we compromise, add it back to the rest of the site where training isn't involved?

Guilty as charged but this was actually unintended, with an apology! I had meant to remove the background and switch to the floating sidebar style only for the training pages but forgot I started to update the CSS and _quarto.yml but never quite completed the necessary changes to limit the changes to the training portal ... Thank you for catching that.

To be honest, this change is rooted in my API work. The preview of the text is just so much cleaner without all the extra visual items on the left and right and it makes the content feel airy. (I basically was using some other docs sites and the ones that resonated with me had a simple, minimalist design that's similar.)

[nrichers]

• Ellipses should have a space before and after, as they are treated as a word in formatting.

This is interesting, at IBM we closed up the ellipsis if it was followed by a punctuation mark. But apparently, that's not what the CMOS says ... I did find this clarification that agrees with you:

Where a comma, semicolon, colon, question mark, or exclamation point follows the ellipsis, it is preceded by a space

[nrichers]

Sidebar again ... I removed the dark vertical line you added and tried switching back to the floating style for the training content as it just looks so much cleaner to me. It's like the text has room to breathe ... 🌬️

However, when I tested this change it doesn't work unless you also change the sidebar for the main site, very much is not in the spirit of compromise. So I undid that but did, separately, simplify the sidebar for the training portal.

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL

[nrichers]

• The fact that we have to use a separate flexbox for each question is an authoring nightmare. Perhaps a use case for our new filtered tables if the layout is gonna be wonky anwyay?

Agreed! I appreciate the readability improvements you made to the new button but the overall authoring experience is too much of 'I'm hacking Tachyons CSS' and not enough of 'I can focus on the content'.

If we can find a way to serve FAQ-style content with less authoring effort, that would be helpful — I would include the main FAQ section that you revised in that effort, where all of the categories are manually added, for example.

[nrichers]

I made some additional tweaks to the "coming soon" text. The idea behind this is sound and much better than using a callout, but the table of contents ends up looking messy. Enter .smallercaps which works for both the ToC and the headings:

Before	After

[github-actions]

A PR preview is available: Preview URL

[validbeck]

Guilty as charged but this was actually unintended, with an apology! I had meant to remove the background and switch to the floating sidebar style only for the training pages but forgot I started to update the CSS and _quarto.yml but never quite completed the necessary changes to limit the changes to the training portal ... Thank you for catching that.

Yes, I think this ties into "we should really start to move the training to its own site project, because right now we're using a bunch of CSS & navbar hacks which is a bit of a mess." All good, I figured if you had actually wanted it to change back you would have actually said something.

To be honest, this change is rooted in my API work. The preview of the text is just so much cleaner without all the extra visual items on the left and right and it makes the content feel airy. (I basically was using some other docs sites and the ones that resonated with me had a simple, minimalist design that's similar.)

I think the ToC doesn't need to be there with the API docs, since it seems to repeat what's in the sidebar... I will the hold the rest of my thoughts on the increasing minimalism of the design until directly asked for input, though.

[validbeck]

Sidebar again ... I removed the dark vertical line you added and tried switching back to the floating style for the training content as it just looks so much cleaner to me. It's like the text has room to breathe ... 🌬️

...

OK, this is clearly what you want, and it's your PR, so I'm gonna bow out of this one I think 😅 I'm not going to win this battle and you're in charge, so I'm just gonna suck it up.

[nrichers]

clearly what you want

This isn’t just about what I want, though, it's about tested design principles? Like these:

• Less is more — Mies van der Rohe’s principle that simplicity and minimalism create clarity and efficiency
• Occam’s razor — The idea that the simplest solution is often the best
• Hick’s law — More choices increase cognitive load, slowing decision-making and reducing clarity
• Gestalt principles — Max Wertheimer’s idea that people perceive simple, organized forms more easily
• 'Good design' principles — Dieter Rams' emphasis on simplicity, functionality, and honesty

And, since that list seriously lacks diversity, how about these?

• "Minimalism hates ornaments, but ornaments love minimalism" — Gesa Hansen on how there is a balance to be struck between simplicity and decorative elements in design
• "The essence of elegance is not the absence of simplicity, but the absence of excess." — Jil Sander on the importance of simplicity that leaves room for more

I would qualify all of these principles with: you have taught me that you look at a page differently and that we can make this a part of our design. It has to be an inclusive design, though, and that includes you AND me.

[validbeck]

I would qualify all of these principles with: you have taught me that you look at a page differently and that we can make this a part of our design. It has to be an inclusive design, though, and that includes you AND me.

Yes, I agree, but this is too minimalist for me. Here are some counterpoints that this article sums up nicely:

• "Accessibility: The lack of contrast between elements could be an accessibility barrier. The subtle color differences might look sleek, but they can make it challenging for users with visual impairments or older screens to distinguish between different parts of the interface. Clear, high-contrast elements are crucial for ensuring that everyone can comfortably navigate and understand the content."
• "Visual Hierarchy: There’s not much differentiation between elements. Everything is similarly weighted, so it’s easy to miss important details like pending transactions or larger sums of money."
• "Flat Design Confusion: The flat design style, which avoids distinct visual separations like raised buttons or shadows, can indeed make it difficult to understand what is interactive and what isn’t. [...] This could lead to user frustration as they might mistakenly click on something thinking it’s a separate column or item when it’s actually part of another option."

Some of how we landed on the current theme is you suggesting that we borrow elements from the Platform UI — which I think was valid and lended cohesion to the docs which is definitely not a bad compromise. But we've moved away from that immediately in favour of more minimalism without more discussion, or actual input from design which is also something that has been suggested should happen when I attempt to make visual changes. The messaging around what you want the design to be has been really inconsistent when it comes to my suggestions, and I can't make sense of it.

[nrichers]

Yes, I agree, but this is too minimalist for me. Here are some counterpoints

Those are very good counterpoints and they reflect the need for inclusive design.

Also, there are standards and I ran an accessibility checker for ADA Section 508 against these sections of our docs site:

• https://docs-staging.validmind.ai/training/program/program-overview.html — my more minimalist sidebar
• https://docs.validmind.ai/get-started/get-started.html — with a higher-contrast sidebar

The results didn't show any discernible difference for the sidebar but I did notice some other things we should discuss. I'll open a story for this — let's discuss there.

The messaging around what you want the design to be has been really inconsistent when it comes to my suggestions, and I can't make sense of it.

We reached a point of saturation, adding things to the the site until it started to affect MY ability to read our site.

Seeing as I am deep in GitHub comments rather than getting ready for tomorrow, how about this? Let's defer the design language for our docs site until we have a designer at the table AND can make sure we meet all the accessibility requirements.