Developer portal — Quick reshuffle to accomodate "ValidMind for model development" series

[validbeck]

Internal Notes for Reviewers

sc-8728

Get started with the ValidMind Library > ValidMind Library

LIVE PREVIEW

• To accommodate for strengthening this section of our docs site into our hub for resources/references for the library instead of more sprawling content that should be corralled into our upcoming Get Started/onboarding restructure, I've renamed this section — especially as it's actually much more than a "Getting Started" page.
  • We have a habit of having multiple copies/using the same terminology for discrete content/ideas so let's improve that when we can.
  • I made sure to include an alias and resolve any direct links in the doc, also this follow-up PR in validmind-library for notebook links out and references to the title for cleanliness: Cleanup of links out to the ValidMind Library docs validmind-library#331
• This landing page got a slight edit, in addition to plunking in the new introductory series. Shortened the conceptual pieces in preparation for a bigger edit when we have a Story for giving this section the TLC it deserves.
  • QuickStart section simplified a bit — we still have the old video here for now but it's a link out instead of a video tile that overwhelms the page.
  • The abstract "Document models" listing with more conceptual fluff is now a What's next-ish section, directing users to the guides on how to continue after logging tests and generating documentation. No nonsense and to the point.

Before	After

Model documentation > QuickStart

New sidebar section. We explain so much more than just model documentation, for one, and this restrictive model documentation-sans-model-validation focus doesn't leave room for us building on these resources for a validation experience.

Supported models

Moved this into just under the landing as it's technically a conceptual/product reference and fixed all links out/added an alias.

Documenting models

• I removed this conceptual fluff and the Document models flow page as it is superfluous. IMO, developer docs should be about doing or learning by doing and not pages and pages of essays about how the product works in theory. Hopefully as we continue to clean up our notebooks the how will no longer be in question.
• The more granular guides (Install & initialize, Store credentials, etc.) remain for now just in case as I do believe they are important reference materials in piecemeal outside of the notebooks where we also link out to these docs, but placed them in the new QuickStart section of the sidebar.
  • "Work with test results" got moved into "Working with model documentation" where it actually belongs — with the rest of the granular platform user guides!

Before	After

Introduction for model developers > ValidMind for model development series

The star of the show — now in its own sidebar section and a step under the QuickStart notebook (which I plan to edit next to complement the series!).

Sidenav	Landing page tiles

Also, a "ValidMind for model validation" would fit right in here now whenever it's ready! ✨

Other notes

• I cleaned up our relative aliases as I realised Quarto is able to resolve those fine for clarity. My bad for not checking on this before (or maybe they updated it recently, idk).
• There were also some relative hotlinks to images in the training — fixed those.

FAQ migrated into Support

• There was agreement here that this should just happen so I took the opportunity while I was reshuffling to move this for cleaner nav/more condensed sections.
• I left the folder structure untouched as we have releases separate as well even though they're in About — just compressed the user end of things.

Before	After

Try the code samples

Changed the button to All code samples but I'm not convinced these are best/most helpful three samples we have at the moment — just some food for thought... might need to wait until we clean up our notebooks/restructure them, but it did stand out to me.

[github-actions]

PR Summary

This pull request refactors the navigation and documentation structure of the project. The changes include:

1. Navigation Updates: The _quarto.yml file has been updated to reorganize the navigation structure. This includes renaming and relocating several menu items and links to improve clarity and accessibility.

   • The "Developers" section now includes updated links and text for better alignment with the content.
   • The "FAQ" section has been restructured to consolidate related topics under a single menu item.

2. Documentation File Relocations: Numerous documentation files have been moved to new locations to better reflect their content and purpose. This includes:

   • Moving files from developer/model-documentation to developer/ and guide/model-documentation.
   • Updating aliases in the front matter of documentation files to ensure backward compatibility with existing links.

3. Alias Updates: Aliases have been updated across multiple files to ensure that old URLs redirect to the new locations, maintaining accessibility and preventing broken links.

4. Notebook Enhancements: Several Jupyter notebooks have been updated with new content and examples, particularly focusing on the ValidMind Library's capabilities and usage.

   • New notebooks have been added to guide users through setting up and using the ValidMind Library for model development.
   • Existing notebooks have been enhanced with additional examples and explanations.

5. Image and Asset Updates: New images and assets have been added to support the updated documentation and notebooks, providing visual aids and examples.

Overall, these changes aim to improve the user experience by making the documentation more organized and easier to navigate, while also enhancing the educational content available to users.

Test Suggestions

• Verify that all updated navigation links in _quarto.yml lead to the correct pages.
• Check that all moved documentation files are accessible via their new paths and that old paths redirect correctly using aliases.
• Ensure that all Jupyter notebooks execute without errors and that new examples function as expected.
• Test the new navigation structure for usability and clarity, ensuring that users can find information easily.
• Validate that all images and assets are correctly displayed in the documentation and notebooks.

[github-actions]

A PR preview is available: Preview URL

[nrichers]

LGTM! 🥳 These are very useful changes on the path to revamping our developer docs.

Since this PR does move the FAQ under "Support": It feels like this could be a drop-down that incorporates support, troubleshooting, and FAQ links but I don't think it should be next to the "Developers" drop-down. If you are amenable to the idea, how about moving this navbar item to the right?

EDIT: If you have some ideas for how to make the validmind.com link less noticeable, I'm all ears. There was an ask to have this link in the navbar, but it sticks out. The solution on other pages is much more elegant.

[validbeck]

Since this PR does move the FAQ under "Support": It feels like this could be a drop-down that incorporates support, troubleshooting, and FAQ links but I don't think it should be next to the "Developers" drop-down. If you are amenable to the idea, how about moving this navbar item to the right?

EDIT: If you have some ideas for how to make the validmind.com link less noticeable, I'm all ears. There was an ask to have this link in the navbar, but it sticks out. The solution on other pages is much more elegant.

I agree, but it's out of the scope of this Story so can you cut a related Story for this? 🙏🏻 Technically we have the ValidMInd site in the footer already so we don't necessarily need it in the header either...

[github-actions]

A PR preview is available: Preview URL

[github-actions]

A PR preview is available: Preview URL