Writing Style & Standards
These rules ensure a consistent voice across all Keymate documentation, regardless of author. For Markdown syntax, components, and page templates see the Writing Guide.
Voice and Tone
-
Use active voice. Write direct sentences where the subject performs the action.
Do Don't Configure the realm in the Admin Console. The realm should be configured in the Admin Console. The Policy Engine evaluates the request. The request is evaluated by the Policy Engine. Click Save to apply changes. Changes can be applied by clicking Save. -
Be clear and empathetic. Assume the reader is competent but unfamiliar with Keymate internals. Guide them without being condescending.
Avoid Dismissive Language
Never use words that trivialize complexity. What feels "simple" to the author may not be simple to the reader.
Avoid: just, simply, easily, obviously, of course, merely.
| Do | Don't |
|---|---|
| Run the migration script. | Just run the migration script. |
| Add the following line to your configuration. | Simply add the following line to your configuration. |
| This process takes a few minutes. | This can easily be done in a few minutes. |
Avoid Unexplained Jargon
When using a domain-specific term for the first time on a page, explain it inline or link to the glossary.
Good:
The [Policy Engine](/glossary/policy-engine) evaluates each access request against
the configured policies.
Bad:
The PE evaluates each request against the configured policies.
Do not assume the reader knows acronyms like RBAC, ABAC, or ReBAC without a definition or link on first use.
Brand and Product Names
Always use the official capitalization and spelling for brands, products, and technologies that are allowed in documentation. Never invent your own abbreviation.
| Correct | Incorrect |
|---|---|
| Keymate | keymate, KeyMate, KEYMATE |
| Keycloak | keycloak, KeyCloak, Key Cloak |
| Kubernetes | kubernetes, K8s (in formal prose) |
| OpenShift | openshift, Openshift |
| Helm | helm, HELM |
| OpenTelemetry | opentelemetry, Opentelemetry, OTel (in formal prose) |
| ArgoCD | argocd, Argocd, Argo CD |
| TypeScript | Typescript, typescript |
| macOS | MacOS, macos, MACOS |
Vendor Neutrality
Keymate has zero vendor dependency. Documentation must never reference specific vendor or product names for infrastructure components. Use generic capability names instead.
Must be replaced
Do not use the product names in the left column. Use the alternative in the right column.
| Do not use | Write instead |
|---|---|
| Kafka, Apache Kafka | event bus |
| PostgreSQL, Postgres | relational database |
| ClickHouse | analytical data store |
| Apache APISIX | API gateway |
| Istio | service mesh |
| Envoy | sidecar proxy |
| Nginx | reverse proxy |
| Kong | API gateway |
| Grafana | metrics dashboard |
| Prometheus | metrics backend |
| Jaeger | trace backend |
| Datadog, SigNoz | observability backend |
| Splunk | log analytics engine |
| OpenFGA | FGA Engine / authorization engine |
| Docker (in prose) | container runtime |
| Docker Compose | do not reference — use make targets or generic "local stack" |
| Docker image | container image |
| Confluent Schema Registry | Schema Registry |
| Confluent Protobuf Serializer | Protobuf serializer |
Allowed as-is
These names do not imply vendor lock-in and may be used without substitution:
| Category | Allowed names |
|---|---|
| Open standards and protocols | OAuth, OIDC, JWT, gRPC, REST, mTLS, SAML, SCIM, DPoP, HTTP/2, WebSocket, GraphQL, OpenAPI, Protobuf |
| Identity and auth | Keycloak |
| Container and orchestration | Kubernetes, OpenShift, Helm, Helm Charts, containerd |
| Observability | OpenTelemetry |
| DevOps | ArgoCD, Kubernetes Operators |
| Cloud providers | AWS, Azure, GCP |
| Programming languages | Java, Kotlin, Go, TypeScript, JavaScript, Python, Lua, Rust, WebAssembly |
Scope
This rule applies to all documentation surfaces: prose, Mermaid diagram labels, code snippets (class names, property keys), frontmatter tags and keywords, FAQ sections, and configuration examples.
CLI commands and file names that exist in the actual codebase (such as Dockerfile, docker-compose.yml, local/docker/) may remain as-is since they refer to real artifacts. Wrap them in Makefile targets when possible to avoid exposing the underlying tool.
Examples and Dummy Data
All code examples, screenshots, and configuration samples must use generic, environment-neutral data. Never include real user information.
| Use | Don't use |
|---|---|
user@example.com | halil@keymate.io |
Jane Doe, Acme Corp | Real employee/company names |
192.0.2.1 (RFC 5737) | Real internal/external IPs |
example.com, test.local | Real domains or staging URLs |
sk_test_placeholder | Real API keys or tokens |
https://auth.example.com | Real identity provider URLs |
Version and Compatibility Callouts
When a feature, API, or configuration option is version-specific, add an admonition so readers know whether it applies to their environment.
:::info[Available since v2.1.0]
The `delegation` scope type requires Keymate Platform v2.1.0 or later.
:::
:::warning[Deprecated since v3.0.0]
The `legacy-auth` endpoint is deprecated and will be removed in v4.0.0.
Use the [Access Gateway](/glossary/access-gateway) instead.
:::
:::caution[Breaking change in v3.0.0]
The `policyId` field in the evaluation response has been renamed to `policy_id`.
Update your client code before upgrading.
:::
Add version callouts when:
- A feature was introduced after the initial release.
- A configuration option or API is deprecated.
- A breaking change affects upgrade paths.
- A code sample relies on a specific SDK or platform version.
UI Element References
When referring to buttons, menus, tabs, labels, or other interface elements, use bold text. Quote the element exactly as it appears in the UI.
Good:
Go to **Identity Providers** and click **Add Provider**.
In the **Policies** tab, select **Create New Policy**.
Bad:
Go to Identity Providers and click Add Provider.
Go to the identity providers section and click the add provider button.
Code Sample Standards
Version Alignment
Every code sample must be accurate for the Keymate version it targets. Follow these rules:
- State the version. If a code sample uses an API or SDK feature specific to a version, add a version callout above the code block.
- Mark deprecated examples. If an older approach is shown for reference, wrap it in a
:::warning Deprecatedadmonition and link to the current alternative. - Test before publishing. Code samples in guides and tutorials must compile/run against the stated version. The reviewer is responsible for verifying this.
:::info[Requires Keymate Java SDK 2.3.0+]
The `evaluateBatch()` method was introduced in SDK v2.3.0.
:::
Review Responsibility
The merge request reviewer must verify that:
- Code samples compile or run without errors against the stated version.
- SDK import paths and method signatures match the current release.
- Configuration keys and values are valid for the documented version.