"Model Workflows" section in Guides

[validbeck]

Internal Notes for Reviewers

Model Workflows	Details
	For sc-3870, I created three (3) net-new docs in a Model Workflows section under Guides to serve as a framework for our workflows feature.

Working with model workflows

• Should say Working with workflows in the side nav
• Links out to Customize resource statuses and Set up model workflows under "What's next"
• Covers reviewing existing workflows attached to models & model documentation, as well as working with workflow-related actions
• Has demonstrative gifs

See PDF: Working with model workflows.pdf

Customize resource statuses

• Covers the setup for statuses used in workflows

See PDF: Customize resource statuses.pdf

Set up model workflows

• Should say Set up workflows in the side nav
• Covers adding/editing/deleting workflow steps and the details of configuration, including conditional requirements
• Has demonstrative gifs

See PDF: Set up model workflows.pdf

Guides

Now has a Model workflows section.

External Release Notes

You can now manage lifecycle processes within your ValidMind Platform UI setup using workflows. Use workflows to match your organizational needs for overseeing model development, validation or implementation activities.

Check out our new documentation on working with your model workflows!

To use workflows, you'll need to:

1. Customize your resource statuses,
2. Then set up your model workflows

[nrichers]

I admire your patience with these docs, @validbeck! I left a bunch of minor consistency comments but this PR does a really nice job of explaining complicated and UI-heavy procedural steps. 😮

[validbeck]

@nrichers Made some changes to the deletion confirmation steps, as seen below:

Delete statuses	Delete workflow steps

I also annotated the screencap for the Request fields as I thought it was important to have the whole context of that step setup, but the box now highlights the specific setup the user should look for within that context:

Otherwise I think the other cases are us disagreeing on style choices, so perhaps we can talk it over today on our sync?

[nrichers]

Otherwise I think the other cases are us disagreeing on style choices, so perhaps we can talk it over today on our sync?

Works for me! I really mainly just care about consistency.

[validbeck]

@nrichers, sorry for the back and forth! I decided to make a quick adjustment to our style guide to accommodate for UI elements that aren't clickable:

My rationale here is breaking types of interactions up with different emphasis helps accessibility (as if everything is bolded, that is confusing too), and you're right that these headers and groupings should also be styled differently than the other body text.

I've made some adjustments to the "Model Workflows" section with this in mind and will also review for this when I do sc-4459. Otherwise, I've modified the copy/navigation to something that's a bit more aligned with your suggestions (more or less).

e.g.

[nrichers]

I decided to make a quick adjustment to our style guide to accommodate for UI elements that aren't clickable

I was hoping to have a conversation on this rather than a unilateral declaration. 🙂 But I do agree that clarity here would be helpful.

FWIW, I checked what Apple, Microsoft, and Google do and they're not 100% consistent but bolding is a very common way they suggest for highlighting UI elements. Google is the clearest:

When referring to any UI element by name, put its name in bold, using the b element in HTML or ** in Markdown. This includes names for buttons, menus, dialogs, windows, list items, or any other feature on the page that has a visible name.

Note the "any".

I have to admit, I'm not a huge fan of having a double rule for bolding and italics, especially as it encourages more references to specific UI elements when users should be focusing on the interaction or using a feature. But let's maybe chat at 4 PM rather than trading GitHub comments. 😄

[nrichers]

LGTM (looks GREAT to me)! Thank you putting this PR together and for helping us sort out our bolding of UI elements. I also appreciate the cropped screenshots, they do a lot to remove visual clutter.

For UI elements, our group decision was to bold only elements you interact with directly, e.g. by clicking. Other UI elements will just use plain text, including section headings in a page or UI elements we refer to. This decision is in keeping with your original way of referring to UI elements which is a simpler, less visually cluttered approach.

[validbeck]

Made some quick changes based on our conversation yesterday:

• Adjusted the style guide for bolding only for specific interaction elements in the UI
• Modified the Workflows docs to reflect this (removed any italicising for headers/grouping elements and just left the casing we see in the UI for wording)
• Quickly removed any secondary links in step-by-steps other than the 1st login to the platform UI step

Style Guide adjust	Example style edits

• @nrichers I know you already approved but just for visibility. I'm also going to do a quick edit to the top-level comment for external release notes.
• Also, do you know if Manage roles & permissions is something I just don't have access to? Or rather, I feel like the roles/permissions has been shifted in the UI and this guide needs to be updated?

[nrichers]

• Also, do you know if Manage roles & permissions is something I just don't have access to?

Do you hold the Customer Admin role? If so, you should see the UI options. I've been using the "Jane Doe" user to test while working with ServiceRocket's writer.

• Adjusted the style guide

Thank you for making these updates and for the discussion yesterday! Maybe outside the scope of this PR, but we also use backticks (``) for emphasis, e.g. for parameter names that are part of the product. Maybe we should start a story to collect future style guide updates?

[validbeck]

Do you hold the Customer Admin role? If so, you should see the UI options. I've been using the "Jane Doe" user to test while working with ServiceRocket's writer.

I do have the Customer Admin role, but I'm saying that the instructions on that page don't line up with what the experience in the UI is like. 😅

but we also use backticks (``) for emphasis, e.g. for parameter names that are part of the product. Maybe we should start a story to collect future style guide updates?

This is true, I'll add to the audit story.

[panchicore]

🍻

[nrichers]

I do have the Customer Admin role, but I'm saying that the instructions on that page don't line up with what the experience in the UI is like. 😅

I understand now — yes, it looks like the Roles & Permissions page has been split up, along with other changes. I'm already chatting with Suba from ServiceRocket and have asked her about updating these docs.