Customize documentation templates

ValidMind offers robust and fully customizable templates for model documentation and validation reports. Configure these templates via multiple methods to suit your organization’s unique needs.

• Templates are versioned and saving a documentation template after making changes or reverting to a previous version state always creates a new version, or you can duplicate templates to create new independent templates in your library.
• Documentation templates are stored as YAML files edited directly using the advanced editor, allowing you full control over the minitua such as desired guidelines.
• We also provide a simplified editing experience to allow you to easily construct and rearrange the outline of your template.

Prerequisites

• You are logged in to ValidMind.
• The template you want to edit must exist in the ValidMind Platform.¹
• You are a Customer Admin or assigned another role with sufficient permissions to perform the tasks in this guide.²

¹ View documentation templates

² Manage permissions

If you are not sure which template or which version of a template your model documentation is using, check the Documentation page of your model.³ The Document Template section in the right sidebar lists the information.

³ Working with model documentation

Edit template outline

1. In the left sidebar, click Settings.

2. Under Workplace Settings, select Templates.

3. Select one of the tabs for the type of template you want to edit:

   • Documentation
   • Validation Report
   • Ongoing Monitoring

4. Locate the template to edit and on the template details page, click Edit Outline.

5. In outline editing mode, you can:

   1. Expand sections:
      • Expand the menu for any sections with subsections by clicking .
   2. Add content to sections:
      • For validation report templates, you’re able to add additional content.
      • Click to add content to that section of the template, such as a Summary Block or a Guideline Block.⁴
   3. Rename sections:
      • Hover over a section until the appears, then click on it to change the name.
      • Save by clicking , and discard changes by clicking .
   4. Insert new sections:
      • Click to add a new section or subsection to the template.
      • To add a section above the current section, select Section Before.
      • To add a section below the current section, select Section After.
      • To add a subsection within the current section, select Subsection.
   5. Remove sections:
      • Click to delete a section.
      • After you confirm, that section will be removed.
   6. Reorder sections:
      • Click and hold firmly to drag to reorder sections.

6. When you’re done, click Create New Version to view a side-by-side comparison of your changes with the previous version:

   • Add a description in version notes to track your changes.
   • Click Save to save the new version.

⁴ Manage validation guidelines

Once saved, your new template version becomes available for use.

Editing a template outline

To add guidelines to your template, edit the YAML template directly.

Edit YAML template

1. In the left sidebar, click Settings.

2. Under Workplace Settings, select Templates.

3. Select one of the tabs for the type of template you want to edit:

   • Documentation
   • Validation Report
   • Ongoing Monitoring

4. Locate the template to edit and on the template details page, click Edit Raw.

5. In the Edit Template YAML editor that opens, make your changes according to the template schema,⁵ then click Continue to view a side-by-side comparison of your changes with the previous version of the template.

6. On the Review Changes screen:

   • Add a description in version notes to track your changes.
   • Click Save Version # to save the new version.

⁵ Template schema

Editing the raw YAML behind a template

Once saved, your new template version becomes available for use.

Template schema

Type: object

root template_id

Type: string

Unique identifier for the template.

root template_name

Type: string

Name of the template.

root version

Type: string

Version of the template.

root description

Type: string

Description of the template.

root sections

Type: array

Documentation sections of the template.

Each item of this array must be:

root sections section

Type: object

root sections sections items id

Type: string

Unique identifier for the section.

root sections sections items title

Type: string

Title of the section.

root sections sections items description

Type: string

Description of the section.

root sections sections items parent_section

Type: string

ID of the parent section.

root sections sections items order

Type: integer

Order of the section in the navigation menu. By default sections are ordered alphabetically. If order is specified, sections will be ordered by the order value, and then alphabetically.

root sections sections items default_text

Type: string

Default text for the section. If set, a metadata content row will be created with this text when installing the template

root sections sections items index_only

Type: boolean

If true, the section will be displayed in the navigation menu, but it will not be accessible via direct link.

root sections sections items condensed

Type: boolean

If true, the section will condense all of its subsections into a single section.

root sections sections items guidelines

Type: array of string

Documentation or validation guidelines for the section.

Each item of this array must be:

root sections sections items guidelines guidelines items

Type: string

root sections sections items contents

Type: array

Contents to be displayed on the section.

Each item of this array must be:

root sections sections items contents section_contents

Type: object

Single content block of the module.

root sections sections items contents contents items content_type

Type: enum (of string) Default: "metadata_text"

Must be one of:

• "metadata_text"
• "dynamic"
• "metric"
• "test"

Examples:

"metadata_text"

"test"

root sections sections items contents contents items content_id

Type: string

ID of the content to be displayed for the given content type (text, tests, etc.).

Examples:

"sample_text"

"section_intro"

root sections sections items contents contents items options

Type: object

Options for the content block.

Examples:

{
    "default_text": "This is a sample text block."
}

{
    "metric_id": "metric_1",
    "title": "Custom Title for Metric 1"
}

{
    "test_id": "adf_test"
}

root sections sections items contents contents items options default_text

Type: string

Default text for the content block. Only applicable for metadata_text content blocks.

root sections sections items contents contents items options title

Type: string

Title of the content block. Only applicable for test content blocks.

Generated using json-schema-for-humans on 2023-06-08 at 14:44:40 -0700

Duplicate template

To duplicate an existing template and start with version one of that new template:

1. In the left sidebar, click Settings.

2. Under Workplace Settings, select Templates.

3. Select one of the tabs for the type of template you want to duplicate:

   • Documentation
   • Validation Report
   • Ongoing Monitoring

4. Locate the template to duplicate and on the template details page, click Duplicate Template.

5. In the Duplicate Template YAML editor that opens, give your copy a template name.

   Optionally, you can also add a template description.

6. Click Duplicate Template to create a copy of your template.

Duplicating a template

Once duplicated, customize your new template to your needs, making it available for use with model documentation or validation reports.

Troubleshooting

The documentation template editor validates the YAML changes you make and flags any errors that it finds. If you make a change that the editor cannot parse correctly, the editor will not let you save the changes until you correct the YAML.

Common issues with YAML include incorrect indenting, imbalanced quotes, or missing colons between keys and values. If you run into issues with incorrect YAML, check the error message provided by the template editor, as it might provide a line and column number where the error occurs.

What’s next

• Swap documentation templates
• Working with model documentation