Updated docs for validation guideline settings

[validbeck]

Internal Notes for Reviewers

For sc-5874 I:

• Revamped preparing-validation-reports.qmd
• Changed view-validation-guidelines.qmd to manage-validation-guidelines.qmd & moved it to the top-level of Model Validation
• Updated customize-documentation-templates.qmd to reflect the new ongoing monitoring feature and added details for expanding/adding content (guidelines) to sections
• Removed Risk areas from set-up-your-organization.qmd & retooled the single-sourcing for this page

Preparing validation reports

• Cleaned up the intro
• Added requirement for validation guideline configuration to prerequisites
• Retooled the Get started section into more accurate instructions on how to interact with validation reports, including information on viewing validation guidelines (I decided this did not need to be its own page or even section, as they are pretty well integrated into the report building process)
• Made sure the What's next included all the other pages under this landing

Old	New

View validation guidelines > Manage validation guidelines

• I retooled the old view validation guidelines page to a net-new page covering how to set up and attach guidelines to validation report templates (the old instructions were incorrect anyhow, as the UI has been updated)
• I moved this page to the top-level model-validation section and placed it above preparing reports as guidelines should ideally be set before reports are made

Old	New
...
...
...

Customize documentation templates

• Adjusted the Edit template outline section to include information on how to expand sections & add content to validation report templates
• Tweaked the wording to include ongoing monitoring templates, more generalized references to templates etc.

Old	New

Set up your organization

• Moved the Risk areas section to the bottom and linked out to manage-validation-guidelines.qmd instead
• I tweaked or cleaned up the other set-up-your-organization.qmd single-sourcing files as well to match this format and made sure they look OK in the training as well

Old	New

Other cleanup

Listings & What's next

• Adjusted the look of some of the listings (layout, content) to better reflect the standard established by more recent articles
• Edited/adapted the What's next section of some articles to be more relevant or comprehensive

Examples:

Old	New

Unified display of + & x

• For consistency, I changed all + signs or circle-plus icons to the plus icon where appropriate (making sure it matched what was in the UI).
• I also changed any x to the FA x icon instead

Example:

Old	New

[validbeck]

Nik: Oops, don't know how I removed the review. Sorry for the double-notif. 🫠

[nrichers]

Will approve after you make the requested changes.

Why I marked this as Request changes:

• Numbered steps without a clear task heading feels like saying 'here, do these steps' without also telling you what the steps do. I’d ask that we avoid or discuss why we should allow this approach in our docs.

• Let's agree not to explain how the UI works, something click X to cancel does not belong. The suggestions I included to delete the text also required reworking some of the surrounding text, but please check I got them right.

Other comments:

• References to things you perform actions on should be in the plural in headings, e.g. #### Add guidelines with an "s" at the end, similar to what you already had for risk areas.

• The After you confirm ... additions that show up in the training modules feel especially useful, thank you! It's a small change but it works really well, IMHO.

[github-actions]

PR Summary

This pull request introduces several enhancements and fixes to the documentation and configuration guidelines within the project. The key changes include:

1. Model Validation Section Updates:

   • Added a new guide for managing validation guidelines (manage-validation-guidelines.qmd).
   • Updated the structure and content of the model validation section to improve clarity and usability.
   • Removed the outdated view-validation-guidelines.qmd file.

2. Configuration Documentation Enhancements:

   • Added new files for business units (_business-units.qmd), risk areas (_risk-areas.qmd), and use cases (_use-cases.qmd).
   • Updated existing configuration guides to include new icons and improve the step-by-step instructions.
   • Enhanced the set-up-your-organization.qmd file to include new sections for business units, risk areas, and use cases.

3. Icon and Formatting Updates:

   • Replaced text-based icons with FontAwesome icons for better visual consistency and readability across multiple files.
   • Updated various guides to use the new icon format, including register-your-first-model.qmd, manage-groups.qmd, manage-permissions.qmd, manage-roles.qmd, and more.

4. Content Reorganization:

   • Reorganized the content in several guides to improve the logical flow and user experience.
   • Added new sections and callouts to highlight important information and prerequisites.

5. Miscellaneous Fixes:

   • Fixed broken links and updated references to ensure all documentation is accurate and up-to-date.
   • Improved the layout and formatting of various guides for better readability.

Test Suggestions

• Verify that the new 'Manage Validation Guidelines' guide is accessible and correctly linked from relevant sections.
• Check that all FontAwesome icons are displayed correctly in the updated guides.
• Ensure that the new business units, risk areas, and use cases guides are correctly included and formatted.
• Test the navigation and links within the 'set-up-your-organization.qmd' file to ensure all sections are accessible.
• Review the updated model validation section to ensure all changes are correctly applied and no outdated information remains.

[validbeck]

Numbered steps without a clear task heading feels like saying 'here, do these steps' without also telling you what the steps do. I’d ask that we avoid or discuss why we should allow this approach in our docs.

Agreed, I think I started adding some lead-in text but didn't for this PR for some reason.

Let's agree not to explain how the UI works, something click X to cancel does not belong. The suggestions I included to delete the text also required reworking some of the surrounding text, but please check I got them right.

I think for this I'm a little torn — sometimes talking around the behaviour sounds way more awkward than describing the behaviour. In this case, isn't "Click x to action" describing a task? How would you word it instead?

References to things you perform actions on should be in the plural in headings, e.g. #### Add guidelines with an "s" at the end, similar to what you already had for risk areas.

I forget why I had this in the singular, I feel like I had a reason but after looking at it again it doesn't seem right LOL

[validbeck]

It was too confusing for me to look at the commit suggestions when pulled down without seeing the full context so I'm just going to redo them manually; sorry!

[validbeck]

Applied the suggestions manually, as I discovered my brain doesn't like the piecemeal commits (can't see them in context of the larger doc, especially when we're working out of single-sourcing files) & if I don't make the change myself I can't seem to understand what happened 😓

I think I applied all the suggestions:

• Describe the action instead of the behaviour (not sure why I had trouble with parsing this, clearly I knew how to fix it...)
• Changed headers to the action you should perform as I retooled the structure of the content

[github-actions]

PR Summary

This pull request introduces several enhancements and new content to the documentation:

1. FontAwesome Icons Integration: Replaces plain text symbols with FontAwesome icons for better visual representation in various documentation files.
2. New Configuration Guides: Adds new guides for managing business units, risk areas, and use cases within the organization.
3. Content Reorganization: Reorganizes and updates existing documentation to improve clarity and usability.
4. Template and Validation Guidelines: Introduces new sections and updates existing ones to manage validation guidelines and templates more effectively.
5. Miscellaneous Updates: Minor updates to existing documentation for better readability and consistency.

Key Changes

• FontAwesome Icons: Updated various buttons and actions to use FontAwesome icons (e.g., {{< fa plus >}}, {{< fa x >}}, {{< fa pencil >}}).
• New Guides: Added _business-units.qmd, _risk-areas.qmd, and _use-cases.qmd for better configuration management.
• Template Management: Enhanced the process of managing validation guidelines and templates.
• Content Reorganization: Improved the structure of several guides for better navigation and readability.
• Miscellaneous: Minor text updates and reorganization for better clarity.

Test Suggestions

• Verify that all FontAwesome icons are displayed correctly in the documentation.
• Check the new configuration guides for completeness and accuracy.
• Ensure that the reorganization of content does not break any existing links or references.
• Test the new template and validation guideline management features to ensure they work as expected.
• Review the updated documentation for any grammatical or typographical errors.

[nrichers]

LGTM! Reviewed the changes based on your latest screenshots and then also spot tested one of the tasks ("Add guidelines to template") — worked perfectly. 🚀🚀🚀