User journey improvements

[nrichers]

Internal Notes for Reviewers

This PR moves the needle on our external docs site with:

• Better conceptual information
• Better workflow overviews
• New AI risk and LLM terminology
• Many content edits, fixed links
• And more ...

Summary of the changes

Landing page (preview)

• Update links and copy

Glossary (preview)

• Create new term definitions for ValidMind, developer terms, AI risk & MRM terms

Get Started (preview) — ‘learning-centric: explain the basics'

• Include user journey info from Andres’ Notion doc
• Improve conceptual overview for dev framework and UI
• Add core concepts (single sourced w/ dev framework section)
• Add high-level workflows via Mermaid diagrams

Quickstart (preview) — ‘task-centric: show how to do things’

• Clean up text
• Move Next Steps (preview) into their own file and relocate to after the Quickstart where they belong & update links

ValidMind overview (preview) — ‘long-form conceptual overview: explain why ValidMind matters`

• Expand opening section with AI and LLM info
• Add contextual information about model risk
• Update to terminology (this topic was heavy on the "MRM" acronym)
• Update illustration

(This topic needs to be improved further in a future PR.)

Developer Framework (preview) — explain the user journey into production with the framework

• Flatten navigation to get rid of old parent topic
• Rework into a getting started topic (was more like a partial conceptual overview)
• Update to explain the iterative approach to the developer user journey
• Add high-level workflows via Mermaid diagrams
• Add end-to-end workflow for documenting models (the mother of all flowcharts turned into a multi-column text cheatsheet)

There were also a number of experiments added more complexity than I would have liked. Most I discarded, but I did keep some additional Mermaid diagrams I experimented with for the developer journey in the site-unused/ folder.

Makefile tweak

• To make deploying to the docs demo site easier for previews, I removed a branch check from our Makefile

External Release Notes

We enhanced the architecture and content of our external docs site to make the user journey more efficient for model developers and model validators who are new to our products:

• Reworked the "Get Started" section to include more conceptual information and an overview of the high-level workflows. Try it ...
• Revised the "Developer Framework" section to provide an end-to-end overview of the workflow that model developers should follow as they adopt the framework. Try it ...

[sydneysugar]

The word "needs" is repeated here.

Suggested change

	<p style="margin-bottom: 16px;/*color: #212529;*/">Automating key aspects of the model risk management process, ValidMind is an AI model risk solution designed for the unique needs documentation and validation needs of model developers and validators.</p>
	<p style="margin-bottom: 16px;/*color: #212529;*/">Automating key aspects of the model risk management process, ValidMind is an AI model risk solution designed for the unique documentation and validation needs of model developers and validators.</p>

[nrichers]

Note to myself: this suggestion needs to be applied to index.qmd, as that is where the HTML source lives.

[cachafla]

Looks great Nik! Some general comments:

• What are your thoughts on renaming validmind-python to developer-framework? Not sure if this helps consolidating our terminology and avoids extra confusion for developers
• Change suggestion. Essentially to add NLP somewhere in the sentence:

Instead of:

ValidMind is a platform designed to simplify key aspects of managing the risk for AI models, machine learning models, and large language models (LLMs) for developers and validators alike.

Something like:

ValidMind is a platform designed to simplify key aspects of managing the risk for AI models, including machine learning models, NLP and large language models (LLMs) for developers and validators alike.

• We recently renamed run_template() to run_documentation_tests() (the latter still works and throws a deprecation warning). The reason we did this was that "running" a template felt like a weird action to expose users. It is more accurate to say that they run a set of documentation tests in order to populate a model documentation template. The new function is the same but reflects better what actually happens behind the scenes. The tests that are run are still the tests that are declared in the documentation template

• On this diagram, do you mean "tests" in plural?

[nrichers]

• What are your thoughts on renaming validmind-python to developer-framework? Not sure if this helps consolidating our terminology and avoids extra confusion for developers

+1 on the rename. The less mental gymnastics people have to perform to make the connection between names, the easier it is for them to get started.

I checked our docs, and we don't currently externalize the validmind-python name at all, so this change would mostly just require internal changes, e.g. to some Makefile changes for docs infra which I can handle.

On this diagram, do you mean "tests" in plural?

I will update the text as suggested, but the current text does look correct to me? Here's the adjectival noun phrase with some brackets around to highlight the text structure: "Add (test and content) blocks".

Thank you for reviewing, @cachafla! Much appreciated. I will incorporate your other comments and publish the updated docs site later today.