Terms we use
Xooshe is still an infrastructure platform. We do not hide that you run real clusters, apps, and databases. We do hide needless Kubernetes jargon when a clearer everyday word works.
This page is the source of truth for UI and docs wording. If a screen and this page disagree, follow this page.
How we choose words
- Prefer the job, not the mechanism. Say what the user is doing (“scale copies”, “open a public URL”), not the Kubernetes object name.
- Keep real infra words when they already mean the right thing. Cluster, app, database, backup, node, and domain stay.
- One preferred term per idea. Do not mix “namespace”, “environment”, and “workspace” for the same thing.
- Technical names live in the glossary footnote, not in every label. Operators who know Kubernetes can map them here.
- Never invent cute metaphors that sound like a consumer app. No “homes”, “gardens”, or “magic boxes”.
Glossary
| We say | Meaning | Avoid in UI | Kubernetes name (reference) |
|---|---|---|---|
| Cluster | Your group of servers that runs apps and databases | “Kubernetes cluster” on every screen | Cluster |
| Node | One server in the cluster | “Worker machine” unless explaining | Node |
| Environment | An isolated place for apps (dev, staging, prod, team) | Namespace (except advanced/import flows) | Namespace |
| App | A running service you deploy and manage | Workload, Deployment, StatefulSet | Deployment / managed app |
| Ready-made app | A packaged app from the catalog (PostgreSQL, Redis, Nginx, …) | Managed app, Helm chart, template stack | Managed / Helm release |
| Database | A managed data store (often PostgreSQL) | Postgres cluster (except when naming the engine) | Postgres cluster / CNPG |
| Instance | One running copy of an app or worker | Pod | Pod |
| Copies | How many instances should stay running | Replicas | Replicas |
| Public URL / Domain | How users reach the app from the internet | Ingress, Ingress host | Ingress |
| Disk / Storage | Persistent disk space attached to an app or database | PVC, PersistentVolumeClaim | PVC |
| Shared variables | Env values reusable across apps in a cluster | Shared envs, ConfigMap soup | Shared env / ConfigMap |
| Background task | Extra process that runs with the app (worker, job) | Process, sidecar deployment | Process / Job |
| Scheduled task | Work that runs on a timetable | CronJob | CronJob |
| Connection file | File used to connect an existing cluster | kubeconfig (except file-picker helper text) | kubeconfig |
| Logs | Live text output from instances | Container stdout | Pod logs |
| Terminal | Interactive shell into a running instance | Exec into pod | kubectl exec |
| Pause | Temporarily stop an app without deleting it | Scale to zero (as the primary label) | Scale / pause |
| Restart | Recreate running instances safely | Rollout restart | Rollout |
Words we keep on purpose
- Cluster — everyone in ops already uses it; “cloud project” would be wrong.
- Node — short and accurate for servers in a cluster.
- Organization / Wallet / Ticket — product features, not K8s concepts.
- Argus — product name for uptime monitoring; do not rename to “uptime tool” in nav.
UI still says X
Some screens lag the glossary. Docs use the preferred term and footnote the control once:
| Preferred | You may still see in the UI |
|---|---|
| Connection file | Add an Existing Kube Config |
| Manage environments | Manage Namespaces |
| Shared variables | Shared Environments |
| Copies | Replica count / replicas |
| Ready-made app | Managed app |
Docs voice
Outcome first, then clicks. Bold text is an exact UI label. One glossary tip per page maximum.
Do not put Prerequisites / Steps / Verify success / Troubleshooting on every page. That skeleton is for one page type only. Matching structure across hubs, concepts, and catalogs makes the docs feel copy-pasted.
| Page type | Job | Shape (use these section names) |
|---|---|---|
| Hub | Orient and route | Pitch → journey → path cards → “Not this section” |
| Concept | Teach one idea | Definition → why (≤3 bullets) → short do-this → naming / mistakes |
| Recipe | Finish one concrete task | Outcome → Before you start only if blockers → action-named H2s (e.g. “Open a ticket”) → You’re done when (short) → If it fails only if useful |
| Tour | Explain a multi-area screen | Outcome → sections named after UI areas (Wallet, Domains, …) |
| Catalog | Pick a ready-made app | Choose this when → What you get → Options table → After deploy |
| Chooser | Pick a path | Decision table → default recommendation → links |
| Debug | Fix something broken | Check first → signals (logs, terminal) → actions → deeper links |
| Operator reference | Deep / K8s-named detail | Marked advanced; day-1 readers stay on Quickstart |
Recipe rules
- Prefer H2s that name the job (“Create the environment”, “Deploy the image”) over the word Steps.
- Skip Before you start when the only requirement is “be signed in”.
- Fold success into You’re done when (3 bullets max), not a ceremony section.
- Support tickets is the density target: status tables and verbs beat template headings.
House rules
- No “depending on your deployment / when the UI offers / as shown in the form” unless you name the real fork.
- End with at most three role-labeled links: Next / Background / If stuck.
- Sentence-case titles.
Short examples
Before: “Select a namespace, then check pod replicas and ingress hosts.”
After: “Select an environment, then check running copies and public URLs.”
Before: “Upload a kubeconfig to add an existing Kubernetes cluster.”
After: “Upload a connection file to add an existing cluster.”
Before: “Only managed apps.”
After: “Only ready-made apps.”
For writers and implementers
- Dashboard copy lives mainly in
locales/en.jsonandlocales/fa.json. Change values, not code keys, unless a key is unused. - Prefer updating labels, empty states, helpers, and toasts first. Leave API error payloads alone.
- When a K8s term must appear (import, advanced config), pair it once: Environment (Kubernetes namespace).
- FA translations should follow the same meanings, not literal English calques of Kubernetes jargon.