Established variable naming conventions#245
Conversation
nrichers
left a comment
There was a problem hiding this comment.
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?
Oops Co-authored-by: Nik Richers <[email protected]>
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
left a comment
There was a problem hiding this comment.
Convention looks good! Please apply to our docs source. 🏅
|
Final version of # 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"
Additional changes
Responsive sizing
|
There was a problem hiding this comment.
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:
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.
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.
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. |
Co-authored-by: Nik Richers <[email protected]>
Internal Notes for Reviewers
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.