Established variable naming conventions

[validbeck]

Internal Notes for Reviewers

For sc-4450, I've drafted the following conventions in _variables.yml for your review:

# VARIABLE NAMING CONVENTIONS
# - Variables for long & short forms should be related (e.g. `developer_framework`, `developer`)
# - Variable names should be descriptive and consistent (e.g. `user_first_name`, `user_last_name`)
# - Use prefixes / suffixes for grouping (e.g. `orderDate`, `orderAmount`)
# - Use snake case (e.g. `developer_framework`)
# - Avoid abbreviations (e.g. `customer_address` NOT `custAddr`) — `vm` for ValidMind is one exception
# - Include enough contextual information (e.g. `invoiceTotal` NOT `total`)



# PRODUCT NAMES
# Names of ValidMind products or core features

# Long form
validmind_platform: "ValidMind Platform UI"
validmind_developer: "ValidMind Developer Framework"
risk_platform: "ValidMind AI risk platform"

# Short form
platform: "platform UI"
developer: "developer framework"


# PRODUCT URLS
# Links to ValidMind hosted web applications
# This section is always prefaced by `vm_`

vm_url: https://app.prod.validmind.ai
vm_privatelink: https://private.prod.vm.validmind.ai
vm_api: https://api.dev.vm.validmind.ai/api/v1/tracking
vm_contact: "[**Contact Us**](https://validmind.com/contact/)"


# HYPERLINKS
# Constructed hyperlinks to ValidMind hosted web applications or other common links

platform_login: "[ValidMind Platform UI](https://app.prod.validmind.ai)"


# ENVIRONMENT 
# Environment versions

python-version: "≧3.8 and <3.11"
valimind_version: v2.0.7

Please DO NOT approve this PR just yet, as I have not yet changed the usage of variables across the docs (waiting for approval first). I will re-request your review once that step is complete.

[nrichers]

Awesome work! I especially like how easy some of these conventions are to follow. 🚀 😮

You said this is a half PR — did you want me to wait with approving before you have made the rest of the changes?

[validbeck]

did you want me to wait with approving before you have made the rest of the changes?

Yes please, it sounds like these are pretty good for now, so I can make the changes across the docs then re-request your review.

@nrichers Newer version:

# VARIABLE NAMING CONVENTIONS:
# - Variables for long & short forms should be related (e.g. `developer_framework`, `developer`)
# - Variable names should be descriptive and consistent (e.g. `user_first_name`, `user_last_name`)
# - Use prefixes / suffixes for grouping (e.g. `order_date`, `order_amount`)
# - Use snake case (e.g. `developer_framework`)
# - Avoid abbreviations (e.g. `customer_address` NOT `cust_addr`) — `vm` for ValidMind is one exception
# - Include enough contextual information (e.g. `invoice_total` NOT `total`)



# PRODUCT NAMES
# Names of ValidMind products or core features

# Long form
validmind_platform: "ValidMind Platform UI"
validmind_developer: "ValidMind Developer Framework"
risk_platform: "ValidMind AI risk platform"

# Short form
platform: "platform UI"
developer: "developer framework"


# PRODUCT URLS
# Links to ValidMind hosted web applications
# This section is always prefaced by `vm_`

# Long form — Text & URL
vm_contact: "[**Contact Us**](https://validmind.com/contact/)"
vm_login: "[ValidMind Platform UI](https://app.prod.validmind.ai)"

# Short form — URL only
vm_url: https://app.prod.validmind.ai
vm_privatelink: https://private.prod.vm.validmind.ai
vm_api: https://api.dev.vm.validmind.ai/api/v1/tracking


# ENVIRONMENT 
# Environment versions

python_version: "≧3.8 and <3.11"
validmind_version: v2.0.7

[nrichers]

Convention looks good! Please apply to our docs source. 🏅

[validbeck]

Final version of _variables.yml:

# VARIABLE NAMING CONVENTIONS:
# - Variables for long & short forms should be related (e.g. `developer_framework`, `developer`)
# - Variable names should be descriptive and consistent (e.g. `user_first_name`, `user_last_name`)
# - Use prefixes / suffixes for grouping (e.g. `order_date`, `order_amount`)
# - Use snake case (e.g. `developer_framework`)
# - Avoid abbreviations (e.g. `customer_address` NOT `cust_addr`) — `vm` for ValidMind is one exception
# - Include enough contextual information (e.g. `invoice_total` NOT `total`)



# PRODUCT NAMES
# Names of ValidMind products or core features

# Long form
validmind_platform: "ValidMind Platform UI"
validmind_developer: "ValidMind Developer Framework"
risk_platform: "ValidMind AI risk platform"

# Short form
platform: "platform UI"
developer: "developer framework"


# PRODUCT URLS
# Links to ValidMind hosted web applications
# This section is always prefaced by `vm_`

# Long form — Text & URL
vm_contact: "[**Contact Us**](https://validmind.com/contact/)"
vm_login: "[ValidMind Platform UI](https://app.prod.validmind.ai)"

# Short form — URL only
vm_url: "https://app.prod.validmind.ai"
vm_privatelink: "https://private.prod.vm.validmind.ai"


# ENVIRONMENT 
# Environment versions

python_version: "≧3.8 and <3.11"
validmind_version: v2.0.7

# Other
api_host: "https://API_HOST.validmind.ai/api/v1"

I replaced all the old versions with the new versions where applicable:

Old	New
vm_platform	validmind_platform
vm_framework	validmind_developer
vm_ui	platform
vm_dev	developer
vm_risk	risk_platform
vm_url	No change.
vm_ui_privatelink	vm_privatelink
api_host	No change, but the value adjusted to: https://API_HOST.validmind.ai/api/v1
contact	vm_contact
vm_login	No change.
python-version	python_version
version	validmind_version

Old API	New API

Additional changes

I widened the body content a little as with our margin footnotes things were getting a little squished. It continues to be responsive when the window size is changed.

Old	New

Responsive sizing

[nrichers]

LGTM! (Looks GREAT to me!) Just some very minor comments for you to look at or make note of.

Other bits I noticed, maybe for a future PR:

• The CONTRIBUTING section might actually be better placed below the RELEASES section to keep ValidMind core product info and ValidMind other info grouped together.

  

• There's some slightly awkward word stutter in some places but it's rare. For example, here the source reads The {{< var validmind_developer >}} is a {{< var developer >}} which could just be rewritten not to use the short and long forms of the same var in one sentence:

  

• Completely unrelated, but headings in callouts look like they need some whitespace magic, similar to how you spaced things out in other areas already:

  

[validbeck]

The CONTRIBUTING section might actually be better placed below the RELEASES section to keep ValidMind core product info and ValidMind other info grouped together.

I think we talked about this before when I first created the section, but I personally prefer Contributing before releases especially as we are trying to push the community aspect! I think our open-source/community is a core part of VM product info.

There's some slightly awkward word stutter in some places but it's rare. For example, here the source reads The {{< var validmind_developer >}} is a {{< var developer >}} which could just be rewritten not to use the short and log forms of the same var in one sentence:

Yeah, I noted this, but this is out-of-scope for just the variables swap. These will be reviewed when I do my accuracy/tone audit of each guide.

Completely unrelated, but headings in callouts look like they need some whitespace magic, similar to how you spaced things out in other areas already:

Yes, I noticed this as well, but haven't gotten around to fixing it. I'll put it on the list to take a look.