ValidMind style guide

A style guide helps create distinct yet unified communication across all areas of a product experience, from in-app interactions to technical documentation and blog posts.

Goals

At ValidMind, we value transparency and accessibility—we aim to speak simply and effectively. We also believe in creating community, by presenting information in a manner that encourages collaboration and feedback from users old and new.

Our processes reflect a holistic journey—accommodating the needs of users begins in the design phase, documentation supplements instead of replaces intuitive or engaging and guided user experiences, and publications should help our audience understand value and maximize their potential with ValidMind.

The following guidelines are meant to reflect these above principles, and ensure that all of our communications adhere to our vision.

Voice and tone

While we work closely with technology, the ValidMind voice prefers a human-first approach. When we adapt our tone to fit the audience and context, we always aim to build a relationship and foster understanding with the person we’re trying to reach.

Concise, but thorough

Be clear and concise. Avoid unnecessary jargon or convoluted language. But when in doubt, clarify; define complex phrases and provide context for product terminology.

Use active voice

The quickest way to accomplish clarity is through use of the active voice. Active voice follows natural speaking patterns, is easy to understand, and reduces ambiguity about responsibilities especially when describing tasks.

Active voice examples

Correct	Incorrect
You’ll need to review the generated content.	The generated content will be reviewed by you.

Don’t be obtuse

• Use exoteric (common) language whenever possible, and provide proper explanations or appropriate resources for technical terms. (You see what we did there? Parentheses—so handy.)
• Acronyms often require domain knowledge that a reader might not have. Avoid acronyms unless you define them first.

Common language & defining acronyms examples

Correct	Incorrect
Model risk management aims to ensure the accuracy and reliability of models, reduce operational risks, and comply with regulatory requirements such as the Comprehensive Capital Analysis and Review (CCAR) and the Dodd-Frank Act Stress Tests (DFAST).	MRM aims to corroborate the accuracy and reliability of models, abate OpRisk, and induce observation with regulatory requirements such as CCAR and DFAS.

Break it down

• Divide complex ideas into simple, digestible parts.
• Bulleted lists are your new best friend!
• Try incorporating different mediums (such as visual aids like images, charts, etc.) to help fortify understanding, and to provide the reader respite from walls of text.

Everybody’s welcome

Engage with your audience in a friendly, open, and encouraging manner. Every reader is here to learn, and at ValidMind we believe that experts are always enthusiastic to share their knowledge.

Appeal to humans

Behind every page, there’s a person. In every word, lies an opportunity to win your audience over.

• Show empathy. Acknowledge user frustrations and celebrate successes.
• Inject humor when appropriate. Sometimes, a touch of levity can make technical subjects more engaging. However, keep in mind context and be judicious when applying humor.

Empathy & humor examples

Correct	Incorrect
User acknowledgement: Documenting findings can be difficult and tedious for even the most seasoned of validators.	User dismissal: For experienced validators, documenting findings is a breeze.
Success toast: Nice work—you’ve successfully registered your first model!	Inappropriate humor: We lost your model documentation, oops! Here, have a pony! (e.g. error message for serious issue)

Be positive

Enable value for your audience, by empowering them.

• Focus on solutions. Instead of highlighting what’s wrong, guide the reader to the right path. When possible, offer workarounds.
• Emphasize benefits. Clearly communicate the positive impacts and how they help the user.

Solutions & benefits examples

Correct	Incorrect
While the layout of these columns on this page is fixed, you can export the data which will allow you to rearrange the information as desired.	You can’t edit this page, or change the layout of these columns.

Make it accessible

• Be inclusive. Knowledge is for everyone, and asks for no qualifications other than curiosity. Use bias-free communication to break down barriers and acknowledge the diversity of our user base.
• Not everyone uses technology the same way. To support as wide an audience as possible, provide alternative means to learn about important concepts. This can include alt tags for images, table headers, and alternative formats such as transcripts for videos.

Bias-free communication & inclusivity examples

Correct	Incorrect
The findings are then submitted to the chair of the MRMG (model risk management group), who will then review the recommendations and provide their status assessments.	The findings are then submitted to the chairman of the MRMG, who will then review the recommendations and provide his status assessments.
{fig-alt="A screenshot of the validation report section 2.1.1. that shows a compliance assessment with the option to link to evidence."}	

Let’s chat

Be professional, but keep it casual and warm. Write like you would speak—imagine explaining the concept to a curious friend.

Make it personal

Address the reader directly by using the second person.

• Second person creates a sense of connection and reinforces a user’s agency when it comes to performing tasks.
• It is also an easy way to remove any assumptions we may have about a user’s role, and reinforces bias-free communication.

2nd person examples

Correct	Incorrect
After completing this QuickStart, you will be able to view your test results as part of your model documentation right in the ValidMind Platform UI.	After completing this QuickStart, the model developer will be able to view the test results as part of the model documentation right in the ValidMind Platform UI.

Avoid stiff formality

• Make use of contractions where appropriate.
• Stay away from overly formal or stilted language.
• If there’s a simpler way to say it: say it!

Informal language examples

Correct	Incorrect
Once you’ve registered the model, you can then grab the unique code snippet that will have been generated for you to use in the next step.	First, you must register the model as this will generate a unique code snippet that needs to be copied. Then, you need to retrieve the code snippet so that you can make use of it in the following step.

Focus on teamwork

Keep your audience involved in the process. Engage the reader with questions, and appeal to their interests.

Audience engagement examples

Correct	Incorrect
What if you were able to more easily, more effortlessly discern uncertainty, unleashing the full potential of your model outputs? That’s the power of ValidMind.	ValidMind easily and effortlessly discerns uncertainty, unleashing the full potential of model outputs.

Conventions

A message can only make an impact when it is received, so presentation is (almost) everything.

Comprehensive assistance

Conveying knowledge and empowering users starts in the product interface. While external documentation can be helpful for supporting advanced functionality, users should not be lost on the basics without further reading.

• Make it interactive. Embedded user tutorials should exist whenever possible, and be intuitive and not obstructive.
• Show only what’s necessary when necessary. Progressive disclosure can help guide workflows as well as minimize visual clutter.

American English

While the ValidMind community spans far and wide, its heart finds its home in Palo Alto, California. When writing for ValidMind, keep things consistent by using American English spelling and grammar conventions.

American English examples

Correct	Incorrect
At the center of this page, you will see the elements organized from most recent to least recent by default.	At the centre of this page, you will see the elements organised from most recent to least recent by default.

Formatting

Sentence case

In general, follow sentence-style capitalization to minimize the confusion of when to capitalize and when not to capitalize.

Sentence case examples

Correct	Incorrect
Get started with ValidMind	Get Started with ValidMind

Headings

• Make them imperative! Individual task headings are a call to action. Gerunds (“-ing”) are acceptable when introducing a set of instructions with individual tasks.
  
• Avoid numbered headings. Most headers do not require numbering, as order can be discerned from context. Numbering headers can make it difficult to shift information around when information changes.
  
• Don’t use terminal punctuation. While headings should be in sentence case, they are not sentences.

Heading examples

Correct	Incorrect
Login to ValidMind	1. Logging into ValidMind.

Emphasis

Use emphatic styling sparingly, in order not to overwhelm the reader with visual distractions.

• Bolding: Some light bolding can be helpful to draw attention to core concepts. Bolding is also used to highlight UI elements that the user can interact with, such as links or buttons.
• Italics: Italics should not be used for emphasis, only for first uses of terms on the page to set the stage.
• Quotation marks: Quotation marks should generally only be employed for quoting speech.

Emphasis examples

Correct	Incorrect
At ValidMind, we value transparency and accessibility—we aim to speak simply and effectively. (e.g. Highlighting the important concept within a sentence.)	At ValidMind, we value transparency and accessibility—we aim to speak simply and effectively. (e.g. Highlighting the entire sentence.)
In the ValidMind Platform UI, click Model Inventory on the left sidebar.	In the ValidMind Platform UI, click “Model Inventory” on the left sidebar.
Uncertainty can be summed up as the difference between reality and the outputs from the model selected to approximate reality.	“Uncertainty” can be summed up as the difference between reality and the outputs from the model selected to approximate reality.
“ValidMind is the only platform today that is purpose-built for model risk management professionals in the banking industry,” Jacobi says.	At ValidMind, we value “transparency and accessibility”—we aim to speak simply and effectively.

Callouts

We use two types of callouts to call attention to supplementary information or issue warnings:

.callout

For supplemental information. Notes and tips should follow this formatting.

.callout-important

For warnings and caveats. Warnings, important information, and cautions should follow this format.

Callouts examples

Correct	Incorrect
::: {.callout title="Example note or tip"}	::: {.callout-note title="Incorrect note"}
::: {.callout-important title="Example warning, important, or caution"}	::: {.callout-warning title="Incorrect warning"}

Content types

Code

• Format code in its own code block.
• Declare the code language within the pre-formatted block to properly trigger syntax highlighting.

Within a Jupyter Notebook, simply use a code cell rather than a markdown cell.

Correct:

%pip install -q validmind

Incorrect:
      Using Python, call %pip install -q validmind.

Parameters, values, and files

Use backticks to enclose keyboard commands, parameters, field values, and file names/extensions.

Backtick examples

Correct	Incorrect
Learn how to store project identifier credentials in a .env file instead of using inline credentials.	Learn how to store project identifier credentials in a “.env” file instead of using inline credentials.
For example, the classifier_full_suite test suite runs tests from the tabular_dataset and classifier test suites to fully document the data and model sections for binary classification model use cases.	For example, the “classifier_full_suite” test suite runs tests from the “tabular_dataset” and “classifier” test suites to fully document the data and model sections for binary classification model use cases.
Under When these conditions are met, you are able to set both AND and OR conditions.	Under When these conditions are met, you are able to set both “AND” and “OR” conditions.

Mathematics

Mathematical formulas should be rendered using LaTeX formatting. On our WordPress blog posts, this is taken care of by the WP Quick LaTeX plugin.

Mathematical formula examples

Correct	Incorrect
\(likes \sim Binomial(n_{feedbacks},p_{like})\)	$likes \sim Binomial(n_{feedbacks},p_{like})$

Proper nouns

In the context of model risk management, proper nouns include specific models, laws, or regulations, such as “Basel IV” or “SR 11-7.” These refer to specific frameworks or guidelines and you spell them with initial capital letters or exactly as indicated by official sources.

• Terms that are not proper nouns include general concepts such as “model validation,” “stress testing,” “risk assessment,” and “backtesting.”
• These are common terms in the field and are not capitalized unless starting a sentence.

Proper noun examples

Correct	Incorrect
SS1/23 – Model risk management principles for banks	Model Validation
validation report	basel 4
machine learning	Financial Services industry

Product names

Within our documentation, you are able to reference constants such as the ValidMind Developer Framework and ValidMind Platform UI via variables.

• Use the variables shown on the table below instead of writing out the phrases to enable consistency between guides everywhere except for image alt text or Mermaid charts.
• If product names need to be updated, simply amend the _variables.yml file to see changes reflected throughout all guides.
• Please note that variables will not work within any of the Jupyter Notebook code samples as these are technically standalone files.

ValidMind product variable keys

Product Name	Variable Key	Description
ValidMind AI risk platform	{{< var vm_risk >}}	Risk platform with a developer framework for documenting and testing models, alongside a platform UI hosting cloud-based tools, APIs, databases, and validation engines.
ValidMind Developer Framework	{{< var vm_framework >}}	Open-source suite of of tools that connects to the platform UI.
ValidMind Platform UI	{{< var vm_platform >}}	Hosted multi-tenant architecture that includes a cloud-based web interface.
developer framework	{{< var vm_dev >}}	Short form of ValidMind Developer Framework.
platform UI	{{< var vm_ui >}}	Short form of ValidMind Platform UI.
https://app.prod.validmind.ai	{{< var vm_url >}}	URL of the ValidMind Platform UI.

Refer also to the glossary for extended information on product names.

Other resources

Google offers Technical Writing Courses for Engineers for free. Go forth and write!

Additional style guides

This style guide is meant to help get you familiar with speaking in the ValidMind voice, but not be an exhaustive list of conventions or rules you should be following when writing.

If it’s specified in our guide, follow those instructions—otherwise, you can check out the guides below for more inspiration:

• Google Style Guides
• Microsoft Writing Style Guide
• Apple Style Guide