Finalizing
Model Documentation

Developer Fundamentals — Module 4 of 4

Click to start

Learning objectives

“As a developer who has logged tests with the ValidMind Library to the ValidMind Platform, I want to refine my model’s documentation, submit my model documentation for approval, and track changes and other updates to my model.”

This final module is part of a four-part series:

Developer Fundamentals

Module 4 — Contents

1. Refine model documentation
2. Submit documentation for approval
3. Collaborate with others
4. Track model activity

First, let’s make sure you can log in to ​ValidMind.

Training is interactive — you explore ​ValidMind live. Try it!

→ , ↓ , SPACE , N — next slide     ← , ↑ , P , H — previous slide     ? — all keyboard shortcuts

Before you begin

• Prerequisite courses
• Log in

To continue, you need to have been onboarded onto ValidMind Academy with the Developer role and completed the first three modules of this course:

Module 1

Module 2

Module 3

Already logged in and refreshed this module? Click to continue.

1. Log in to check your access:

Log in to ​ValidMind

Be sure to return to this page afterwards.

2. After you successfully log in, refresh the page to connect this training module up to the ValidMind Platform:

Refine model documentation

Review test results

(Scroll down for the full instructions.)

Learn more …

Try it live on the next page.

After you have added a test result to your document, you can view the following information attached to the result:

• History of values for the result
• What users wrote those results
• Relevant inputs associated with the result

View test result metadata

From the ValidMind Platform:

1. In the left sidebar, click Inventory.

2. Select the name of your model you registered for this course to open up the model details page.

3. In the left sidebar that appears for your model, click Documentation.

4. Locate the test result whose metadata you want to view.

5. Hover over the test result until the top-right hand corner menu appears and select See Timeline:

   • The Active (most recent) test result is highlighted.
   • On the test result timeline, click on the associated with a test run to expand for details, such as Model Information or Dataset Information.

   When you are done, you can either click Cancel or to close the metadata menu.

Review model documentation

1. From the Inventory, select the name of your model you registered for this course to open up the model details page.
2. On the left sidebar that appears for your model, click Documentation.
3. Click into any section of the documentation to review the test results logged via the ValidMind Library.
   For example: 2.3 Correlations and Interactions / 3.2 Model Evaluation

When you’re done taking a look around, click to continue.

Make qualitative edits

(Scroll down for the full instructions.)

Learn more …

Try it live on the next page.

• Add content blocks
• Edit test result descriptions

In any section of your model documentation, hover your mouse over the space where you want your new block to go until a horizontal dashed line with a sign appears that indicates you can insert a new block:

Adding a content block in the UI

After adding the block to your documentation, generate a content draft with AI using the content editing toolbar:

1. Click ^beta (Generate Text with AI) in the toolbar while editing a content block.

2. Enter an optional prompt to guide the output, then click Generate Content to compose a draft for review.

3. Review the draft composed by the ​ValidMind AI Content Builder for accuracy and relevance, then:

   • Click Insert to document to add the draft into your content block.
   • Or, submit a different prompt in the dialogue box and click Send to regenerate a different draft.

4. After you insert the AI-generated draft, click on the text box to make the necessary edits and adjustments to your copy, ensure that content is in compliance with the quality guidelines outlined by your organization.

Generating content with AI within a simple text block

You can also use the content editing toolbar to revise the description of test results to explain the changes made to the raw data and the reasons behind them.

For example:

1. Locate the Data Preparation section and click on 2.3 Correlations and Interactions to expand that section.

2. Click on the text to edit the description for our individually inserted HighPearsonCorrelation:balanced_raw_dataset test:

Screenshot showing description added to the new content block

Add & edit content blocks

1. From the Inventory, select the name of your model you registered for this course to open up the model details page.
2. On the left sidebar that appears for your model, click Documentation.
3. Click into any section of the documentation to add or edit a content block.

When you’re done, click to continue.

Submit documentation for approval

Transition model status

(Scroll down for the full instructions.)

Learn more …

Try it live on the next page.

When you’re ready, verify the approval workflow, and then submit your model documentation for approval:

• Verify workflow
• Submit for approval

Workflow states and transitions are configured by an administrator in advance, but you should verify that the expected people are included in the approval process.

1. Select a model or find your model by applying a filter or searching for it.

2. On the landing page of your model, locate the model status section:

   • Click See Workflow to open the detailed workflow associated with that model.
   • The current workflow state will be highlighted on this detail view.

While your lifecycle statuses and workflows are custom to your organization, some examples are:

• In Documentation — The model is currently being documented and can be submitted for validation next.
• In Validation — The model is currently being validated and can be submitted for review and then approval.

To transition through the approval workflow, all required workflow steps must be completed. By default, a model must be in the
In Documentation state before you can submit it for validation.

1. Select a model or find your model by applying a filter or searching for it.

2. If an action is available to your role, you’ll see it listed under your model status on the model’s landing page.

   • Click to open up the transition panel for your selected action. This arrow will be followed by the action name.
   • Enter your notes and any other additional inventory fields then click Submit.

While your lifecycle statuses and workflows are custom to your organization, some examples are:

• To submit model documentation for validation — Click Ready for Validation to indicate that a model developer has completed the initial model documentation and is ready to have it validated. Add any notes that need to be included and then click Ready for Validation.
• To submit validation reports for review and approval — Click Ready for Review to indicate that you have completed your initial model validation report, fill in the mandatory notes, and submit.
• To request revisions to model documentation or validation reports — Click Request Revision, fill in the mandatory notes to explain the changes that are required, and submit.
• To have your model documentation and validation report approved — Click Ready for Approval, fill in the mandatory notes, and submit.

Submit for approval

1. From the Inventory, select the name of your model you registered for this course to open up the model details page.
2. Locate the model status section.
3. Open up the status transition panel, enter your notes and any other additional inventory fields, then click Submit.

When you’re done, click to continue.

Collaborate with others

Comment threads

Learn more …

Try it live on the next page.

While working with content blocks in documentation, you can comment directly on specific portions of the text.

All users associated with a model, such as model developers and model validators, will see a notification that a comment has been posted in their Recent Activity feed, accessible via the Dashboard.

• Post comments
• Reply to comments
• Resolve comments

1. In any section of the model documentation, select the portion of text you want to comment on, then click the button that appears.

2. Enter your comment and click Comment.

3. You can view the comment by clicking the highlighted text. Comments will also appear in the right sidebar.

1. Click the highlighted text to view the comment thread.

2. Enter your comment and click Reply.

3. You can view the comment thread by clicking the highlighted text.

1. Click the highlighted text portion to view the thread, then click to resolve the thread.

2. To view the resolved comment thread, click the Comments archive button in the toolbar.

   You can view a history of all archived comments in the Comment archive.

To reopen a comment thread, reply to the comment thread in the Comment archive or click the Reopen button that appears next to the highlighted text portion.

Comment on model documentation

1. From the Inventory, select the name of your model you registered for this course to open up the model details page.
2. In the left sidebar that appears for your model, click Documentation.
3. In the content block you added earlier: Post a comment, reply to it, and then resolve the thread.

When you’re done, click to continue.

Track model activity

Track changes & updates

Learn more …

Try it live on the next page.

View documentation activity

The Model Activity page shows a record of all activities, including actions performed by users in your organization and updates generated via the library such as:

• Inventory fields updated on the model
• Model or documentation status transitions
• Updates to model documentation, validation reports, or ongoing monitoring plans
• Test results added to your model
• Findings added, updated, or removed
• Comment creation and replies

To view model activity:

1. In the left sidebar, click Inventory.

2. Select a model or find your model by applying a filter or searching for it.

3. In the expanded sidebar that appears for your model, click Model Activity.

Review model activity

1. From the Inventory, select the name of your model you registered for this course to open up the model details page.
2. In the left sidebar that appears for your model, click Model Activity.
3. Filter the following activity: Comments | Status Updates | Model Updates | Test Results

When you’re done, click to continue.

In summary

Finalizing model documentation

Want to learn more? Find your next learning resource on ValidMind Academy.

In this final module, you learned how to:

• View logged test result metadata
• Add or edit content blocks in your model documentation
• Submit your model documentation for approval
• Collaborate with other stakeholders on your model
• Track updates on your model

There is more that ​ValidMind can do to help you create model documentation, from using your own template to code samples you can adapt for your own use case:

All model documentation guides