Adding guidelines around casing for features.
Content draft:
"1. General references (sentence case)
When speaking conceptually or generally about features within a cluster or UI, use sentence case (capitalize only the first letter of the first word of a sentence and any proper nouns). Do not use special formatting like backticks. This improves readability and treats the object as a common noun.
When to use: Descriptive text, help text, or when explaining a workflow.
Examples:
“You can attach a persistent volume to your pod to ensure data is saved.”
“After you create your storage class, it can be used by any developer in the namespace."
"View resource usage."
“Ensure all storage class names are defined in the manifest.”
- Technical API references (exact case)
When referring specifically to the actual API object, the underlying resource type (like a custom resource definition), use the exact casing defined in the API specification. The formatting depends on the UI placement:
In body text (Use code formatting): Use backticks, brackets, or other code format identifiers to visually distinguish the “code” reference from the prose.
Example (PascalCase): “The PersistentVolume must be in a Bound state.”
Example (camelCase): “Ensure the storageClassName is defined in the manifest.”
Example (snakecase): “The system checks the volumeid before mounting.”
In navigation and page titles (no code formatting): If a page displays a list or details of user-created instances derived from a specific API resource type, the navigation item and page title must match the API casing exactly. The reasoning is that these pages are views of specific data objects (e.g., VirtualMachine), not just generic concepts. Do not use backticks or code formatting in these areas to keep the interface clean.
Example (nav item): StorageMap
Example (page title): StorageMap details
In action buttons(no code formatting): If the action creates an object defined by the API, the button label must use the exact casing of that API resource. “Create” buttons should reference the singular version. Do not use backticks or code formatting.
Example: Create UserDefinedNetwork
Examples:
Virtual machines:
Sentence case: "You can migrate your existing virtual machines from VMware directly into OpenShift."
Why: You are talking about the broad technology and the user's workload.
API casing: "The VirtualMachine must be in a Stopped state before you can change the CPU limits."
Why: You are referring to the specific API reference and its status field.
Instance types:
Sentence case: "You can choose an optimized instance type to improve the performance of your database workloads."
Why: You’re referring to the concept of hardware sizing, not a specific line of code.
API casing: "The controller will return a validation error if the instanceType is not supported by the underlying cloud provider's region."
Why: You’re referring to the specific property key used in API payloads or resource manifests.
" https://docs.google.com/document/d/1W-atwkCjA3GDodeSpVbEPq-UgLHEVghkM9wQdkYvt40/edit?tab=t.fwkpvwfdiyho
Jira Issue: PF-4030
Adding guidelines around casing for features.
Content draft:
"1. General references (sentence case)
When speaking conceptually or generally about features within a cluster or UI, use sentence case (capitalize only the first letter of the first word of a sentence and any proper nouns). Do not use special formatting like backticks. This improves readability and treats the object as a common noun.
When to use: Descriptive text, help text, or when explaining a workflow.
Examples:
“You can attach a persistent volume to your pod to ensure data is saved.”
“After you create your storage class, it can be used by any developer in the namespace."
"View resource usage."
“Ensure all storage class names are defined in the manifest.”
When referring specifically to the actual API object, the underlying resource type (like a custom resource definition), use the exact casing defined in the API specification. The formatting depends on the UI placement:
In body text (Use code formatting): Use backticks, brackets, or other code format identifiers to visually distinguish the “code” reference from the prose.
Example (PascalCase): “The PersistentVolume must be in a Bound state.”
Example (camelCase): “Ensure the storageClassName is defined in the manifest.”
Example (snakecase): “The system checks the volumeid before mounting.”
In navigation and page titles (no code formatting): If a page displays a list or details of user-created instances derived from a specific API resource type, the navigation item and page title must match the API casing exactly. The reasoning is that these pages are views of specific data objects (e.g., VirtualMachine), not just generic concepts. Do not use backticks or code formatting in these areas to keep the interface clean.
Example (nav item): StorageMap
Example (page title): StorageMap details
In action buttons(no code formatting): If the action creates an object defined by the API, the button label must use the exact casing of that API resource. “Create” buttons should reference the singular version. Do not use backticks or code formatting.
Example: Create UserDefinedNetwork
Examples:
Virtual machines:
Sentence case: "You can migrate your existing virtual machines from VMware directly into OpenShift."
Why: You are talking about the broad technology and the user's workload.
API casing: "The VirtualMachine must be in a Stopped state before you can change the CPU limits."
Why: You are referring to the specific API reference and its status field.
Instance types:
Sentence case: "You can choose an optimized instance type to improve the performance of your database workloads."
Why: You’re referring to the concept of hardware sizing, not a specific line of code.
API casing: "The controller will return a validation error if the instanceType is not supported by the underlying cloud provider's region."
Why: You’re referring to the specific property key used in API payloads or resource manifests.
" https://docs.google.com/document/d/1W-atwkCjA3GDodeSpVbEPq-UgLHEVghkM9wQdkYvt40/edit?tab=t.fwkpvwfdiyho
Jira Issue: PF-4030