validmind · validbeck · Aug 22, 2024 · Aug 21, 2024 · Aug 21, 2024 · Aug 21, 2024
diff --git a/site/_quarto.yml b/site/_quarto.yml
@@ -42,6 +42,8 @@ website:
           file: developer/get-started-developer-framework.qmd
         - text: "{{< fa cubes >}} Supported Models"
           file: developer/model-documentation/supported-models.qmd
+        - text: "{{< fa book-medical >}} Generating Model Documentation"
+          file: developer/model-documentation/generating-model-documentation.qmd
         - text: "---"
         - text:  "{{< fa vial >}} TESTING"
         - text: "{{< fa flask-vial >}} Run Tests & Test Suites"
@@ -255,9 +257,12 @@ website:
         - text: "Introduction for model developers"
           file: notebooks/tutorials/intro_for_model_developers.ipynb
         - developer/model-documentation/supported-models.qmd
-        - developer/model-documentation/generate-model-documentation.qmd
-        - developer/model-documentation/install-and-initialize-developer-framework.qmd 
-        - developer/model-documentation/store-credentials-in-env-file.qmd
+        - file: developer/model-documentation/generating-model-documentation.qmd
+          contents:
+            - developer/model-documentation/generate-model-documentation.qmd 
+            - developer/model-documentation/install-and-initialize-validmind.qmd 
+            - developer/model-documentation/work-with-test-results.qmd
+            - developer/model-documentation/store-credentials-in-env-file.qmd
         - text: "---"
         - text: "MODEL TESTING"
         - text: "Run tests & test suites"

diff --git a/site/about/glossary/_developer-tools.qmd b/site/about/glossary/_developer-tools.qmd
@@ -19,7 +19,7 @@ JupyterHub
 
 ValidMind uses JupyterHub to share live code, how-to instructions, and visualizations via notebooks as part of our getting started experience for new users.
 
-Jupyter notebook
+Jupyter Notebook
 : Allows users to create and share documents containing live code, data visualizations, and narrative text. Supports various programming languages, most notably Python, and is widely used for data analysis, machine learning, scientific research, and educational purposes. 
 
 ValidMind uses notebooks to share sample code and how-to instructions with users that you can adapt to your own use case.

diff --git a/site/developer/get-started-developer-framework.qmd b/site/developer/get-started-developer-framework.qmd
@@ -7,11 +7,13 @@ listing:
     max-description-length: 250
     sort: false
     fields: [title, description]
+    grid-columns: 2
     contents:
     - ../notebooks/quickstart_customer_churn_full_suite.ipynb
     - ../notebooks/tutorials/intro_for_model_developers.ipynb
 #    - developer-getting-started-video.qmd
   - id: developer-how-to-beginner
+    grid-columns: 2
     type: grid
     max-description-length: 250
     sort: false
@@ -29,7 +31,14 @@ listing:
     - ../notebooks/code_samples/customization/customizing_tests_with_output_templates.ipynb
     - ../notebooks/code_samples/nlp_and_llm/prompt_validation_demo.ipynb
     - ../notebooks/code_samples/time_series/quickstart_time_series_full_suite.ipynb
-
+  - id: developer-workflow
+    type: grid
+    grid-columns: 2
+    max-description-length: 250
+    sort: false
+    fields: [title, description]
+    contents:
+    - model-documentation/generating-model-documentation.qmd
 ---
 
 The {{< var validmind.developer >}} helps you streamline model documentation by automating the generation of drafts. All you need to do is upload your documentation artifacts and test results to the ValidMind platform.
@@ -67,11 +76,12 @@ The {{< var vm.developer >}} is designed to be model agnostic. If your model is
 :::
 :::
 
-After you [**sign up**]({{< var url.us1 >}}) for ValidMind to get access, try one our getting started guide:
+After you [**sign up**]({{< var url.us1 >}}) for ValidMind to get access, try one of our getting started guides:
 
 :::{#developer-getting-started}
 :::
 
+
 ## Learn how to run tests
 
 ValidMind provides many built-in tests and test suites which make it easy for developers to automate their model documentation. Start by running a pre-made test, then modify it, and finally create your own test: 
@@ -97,3 +107,9 @@ After you have tried out the {{< var vm.developer >}}, continue [working with yo
 - Work with documentation templates to customize them to your specific needs
 - Work with model documentation in the UI to make edits, collaborate with validators, and submit your model documentation for approval
 - Export your finalized model documentation
+
+For more in-depth guides, check out our breakdown of your complete journey as a model developer with ValidMind: 
+
+:::{#developer-workflow}
+:::
+
diff --git a/site/developer/model-documentation/generate-model-documentation.qmd b/site/developer/model-documentation/generate-model-documentation.qmd
@@ -1,128 +1,76 @@
 ---
-title: "Generate model documentation"
+title: "Document models"
 date: last-modified
 ---
 
-## How do I use the {{< var validmind.developer >}}?
+Generate model documentation starting with your model or model predictions, load your model or predictions into the {{< var vm.developer >}}, then finally view the results and refine your documentation in the {{< var vm.platform >}} to make it ready for approval.
 
-A typical high-level workflow for model developers consists of four major steps:
+::: {.prereq}
 
-```{mermaid}
-graph LR
-    A[Develop<br>model] --> B[Generate model<br>documentation]
-    B --> C[Refine model<br>documentation]
-    C --> D[Submit for review]
-    C --> B
-```
-<br> 
+## Prerequisites 
 
-1. **Develop your model**[^1] — In your existing developer environment, build one or more candidate models that need to be validated. This step includes all the usual activities you already follow as a model developer. 
+- [x] {{< var link.login >}}
+- [x] You are the model owner.
+- [x] You are a `Developer` or assigned another role with sufficient permissions to perform the tasks in this guide.[^1]
 
-2. **Generate model documentation** — With the {{< var validmind.developer >}}, generate automated model documentation and run validation tests. This step includes making use of the automation and testing functionality provided by the {{< var vm.developer >}} and uploading the output to the {{< var vm.platform >}}. You can iteratively regenerate the documentation as you work though the next step of refining your documentation.
-
-3. **Refine model documentation** — In the {{< var validmind.platform >}}, review the generated documentation and test output. Iterate over the documentation and test output to refine your model documentation. Collaborate with other developers and model validators to finalize the model documentation and get it ready for review. 
-
-4. **Submit for review** — In the {{< var validmind.platform >}}, you submit the model documentation for review which moves the documentation workflow moves to the next phase where a model validator will review it.
-
-Before you can use the {{< var validmind.developer >}}, you need to verify that the current documentation template contains all the necessary tests for the model you are developing: 
-
-- The template might already be sufficient and you only need to run the template within the {{< var vm.developer >}} to populate documentation. 
-
-- Or, more likely, the template might need additional tests that you can add these tests via the {{< var vm.developer >}}. 
-
-## How do I generate documentation?
-
-This process of verifying the suitability of the the current documentation template and adding more tests to the template is an iterative process:
-
-```{mermaid}
-graph LR
-    A[Verify template] --> B[Build template]
-    B --> D[Add tests and<br>content blocks]
-    D --> E[Add external<br>test providers]
-    E --> C[Run template]
-    C --> B
-
-```
-<br>
-
-Build the template
-: When the documentation template requires more tests to be added, or if the documentation template does not include a specific content or test block you need: 
-
-   - For functionality provided by the {{< var validmind.developer >}} — [Add the relevant tests or content blocks](/guide/model-documentation/work-with-content-blocks.qmd) for the model use case. 
-
-   - For tests not provided by the {{< var vm.developer >}} — [Add your own external test provider](/notebooks/code_samples/custom_tests/integrate_external_test_providers.ipynb).
-
-
-Run the template
-: When you have registered all the required tests as content blocks in the documentation template, populate the necessary model documentation by adding this call to your model:
-
-
-   ```python
-   run_documentation_tests()
-   ```
-
-
-::: {.callout-important title="ValidMind may not support all potential use cases or provide a universally applicable documentation template."}
- Typically, you initiate the process of putting ValidMind into production by constructing a template specific for your own use case and then refine your the documentation project.
 :::
 
-## End-to end workflow
-
-### In your modeling environment
-
-1. Build your model.
+## End-to-end workflow  
 
-2. Export the datasets and model.
+### 1. In your modeling environment
 
-Next, go to **With the {{< var validmind.developer >}}, Step 2**.  {{< fa arrow-right >}}
+1. Build your model or your model predictions.[^2]
 
-### With the {{< var validmind.developer >}}
+2. Export the datasets and model or predictions.
 
-1. Create a notebook to select and build the relevant tests.
+### 2. With the {{< var validmind.developer >}}
 
-2. {{< fa arrow-right >}} **From your modeling environment**, load the trained datasets and models.
+1. **From your modeling environment**, load the trained datasets and models or predictions.
 
-3. {{< fa arrow-right >}} Use the instructions from **In the {{< var vm.platform >}}, Step 3**, [initialize the {{< var validmind.developer >}}](install-and-initialize-developer-framework.qmd).
+2. [Install and initialize ValidMind.](install-and-initialize-validmind.qmd)
 
-4. Select the relevant tests.
+3. Select the relevant tests.
 
-5. Review if all tests are covered by ValidMind or your external test provider:
+4. Review if all tests are covered by ValidMind or your external test provider:
 
-   - If all tests are NOT covered — Create and register additional tests.
-   - If all tests are covered — 
+   - **If all tests are NOT covered** — Create and register additional tests.
+   - **If all tests are covered** — 
       a. Run the selected tests.
       b. Review your test results. 
 
-Next, go to **In the {{< var validmind.platform >}}, Step 5**.  {{< fa arrow-right >}} 
+### 3. In the {{< var validmind.platform >}}
 
-### In the {{< var validmind.platform >}}
-
-1. [Register a new model](/guide/model-inventory/register-models-in-inventory.qmd).
-
-2. Review the template structure.
-
-3. [Locate the {{< var vm.developer >}} integration instructions](install-and-initialize-developer-framework.qmd#locate-the-framework-integration-instructions). 
-
-4.  Go to **With the {{< var validmind.developer >}}, Step 3**. {{< fa arrow-right >}}
-
-5. {{< fa arrow-right >}} After **With the {{< var validmind.developer >}}, Step 6**, [add content blocks](/guide/model-documentation/work-with-content-blocks.qmd) to your model documentation: 
+1. **After installing and initalizing the {{< var validmind.developer >}}**,[^4] add content blocks[^3] to your model documentation: 
 
    Select the block type:
 
-      - For test-driven blocks: Select from available test provider results
-      - For text blocks: 
+      - **For test-driven blocks** — Select from available test provider results[^5]
+      - **For text blocks** — 
 
-         - For new block:
-            - Add new editable text content block
-            - Review and collaborate on the content block
-         - For existing blocks: Select from available texts from content provider
+         a. For new block:
+            1. Add new editable text content block
+            2. Review and collaborate on the content block
+         b. For existing blocks: Select from available texts from content provider
+
+2. [Submit your model documentation for review](/guide/model-documentation/submit-for-approval.qmd).
 
-6. [Submit your model documentation for review](/guide/model-documentation/submit-for-approval.qmd).
+## What's next 
+
+- [Store project credentials in `.env` files](store-credentials-in-env-file.qmd)
+- [Work with test results](work-with-test-results.qmd)
 
 
 <!-- FOOTNOTES -->
 
-[^1]: 
+[^1]: [Manage permissions](/guide/configuration/manage-permissions.qmd)
+
+[^2]: 
 
    **No available model?**<br>
-   You can still run tests and log documentation with ValidMind as long as you're able to [load the model predictions](/faq/faq-documentation.qmd#can-i-run-tests-and-log-documentation-without-having-a-model-available). 
+   You can still run tests and log documentation with ValidMind as long as you're able to [load the model predictions](/faq/faq-documentation.qmd#can-i-run-tests-and-log-documentation-without-having-a-model-available). 
+
+[^3]: [Work with content blocks](/guide/model-documentation/work-with-content-blocks.qmd)
+
+[^4]: [Install and initialize ValidMind](install-and-initialize-validmind.qmd)
+
+[^5]: [Work with test results](work-with-test-results.qmd)
diff --git a/site/developer/model-documentation/generating-model-documentation.qmd b/site/developer/model-documentation/generating-model-documentation.qmd
@@ -0,0 +1,101 @@
+---
+title: "Documenting models"
+date: last-modified
+listing:
+  - id: generate-documentation
+    type: grid
+    grid-columns: 2
+    max-description-length: 250
+    sort: false
+    fields: [title, description]
+    contents:
+    - generate-model-documentation.qmd
+    - install-and-initialize-validmind.qmd
+    - work-with-test-results.qmd
+    - store-credentials-in-env-file.qmd
+---
+
+Use the {{< var vm.developer >}} to generate model documentation, view the results and refine your documentation in the {{< var vm.platform >}}, and collaborate with your team to complete documentation and validation projects within the same interface.
+
+## How do I use the {{< var validmind.developer >}}?
+
+A typical high-level workflow for model developers consists of four major steps:
+
+```{mermaid}
+%%| fig-align: center
+graph LR
+    A[Develop<br>model] --> B[Generate model<br>documentation]
+    B --> C[Refine model<br>documentation]
+    C --> D[Submit for review]
+    C --> B
+```
+<br> 
+
+#### 1. Develop your model[^1]  
+
+In your existing developer environment, build one or more candidate models that need to be validated. This step includes all the usual activities you already follow as a model developer. 
+
+#### 2. Generate model documentation
+
+With the {{< var validmind.developer >}}, generate automated model documentation and run validation tests. This step includes making use of the automation and testing functionality provided by the {{< var vm.developer >}} and uploading the output to the {{< var vm.platform >}}. You can iteratively regenerate the documentation as you work though the next step of refining your documentation.
+
+#### 3. Refine model documentation
+In the {{< var validmind.platform >}}, review the generated documentation and test output. Iterate over the documentation and test output to refine your model documentation. Collaborate with other developers and model validators to finalize the model documentation and get it ready for review. 
+
+#### 4. Submit for review
+In the {{< var validmind.platform >}}, you submit the model documentation for review which moves the documentation workflow moves to the next phase where a model validator will review it.
+
+Before you can use the {{< var validmind.developer >}}, you need to verify that the current documentation template contains all the necessary tests for the model you are developing: 
+
+- The template might already be sufficient and you only need to run the template within the {{< var vm.developer >}} to populate documentation. 
+- Or, more likely, the template might need additional tests that you can add these tests via the {{< var vm.developer >}}. 
+
+## How do I generate documentation?
+
+This process of verifying the suitability of the the current documentation template and adding more tests to the template is an iterative process:
+
+```{mermaid}
+%%| fig-align: center
+graph LR
+    A[Verify template] --> B[Build template]
+    B --> D[Add tests and<br>content blocks]
+    D --> E[Add external<br>test providers]
+    E --> C[Run template]
+    C --> B
+
+```
+<br>
+
+#### Build the template
+
+When the documentation template requires more tests to be added, or if the documentation template does not include a specific content or test block you need: 
+
+   - **For functionality provided by the {{< var validmind.developer >}}** — [Add the relevant tests or content blocks](/guide/model-documentation/work-with-content-blocks.qmd) for the model use case. 
+   - **For tests not provided by the {{< var vm.developer >}}** — [Add your own external test provider](/notebooks/code_samples/custom_tests/integrate_external_test_providers.ipynb).
+
+
+#### Run the template
+
+When you have registered all the required tests as content blocks in the documentation template, populate the necessary model documentation by adding this call to your model:
+
+   ```python
+   run_documentation_tests()
+   ```
+
+::: {.callout-important title="ValidMind may not support all potential use cases or provide a universally applicable documentation template."}
+ Typically, you initiate the process of putting ValidMind into production by constructing a template specific for your own use case and then refine your the documentation project.
+:::
+
+
+## What's next
+
+:::{#generate-documentation}
+:::
+
+
+<!-- FOOTNOTES -->
+
+[^1]: 
+
+   **No available model?**<br>
+   You can still run tests and log documentation with ValidMind as long as you're able to [load the model predictions](/faq/faq-documentation.qmd#can-i-run-tests-and-log-documentation-without-having-a-model-available).