The domains registry calls a domain a name and a served domain a placement, and neither word says what it is #37

Open
opened 2026-09-21 07:18:12 +00:00 by cgalo5758 · 2 comments
Owner

The question

The registry's vocabulary has three words a newcomer has to learn before the Domains page or its documentation makes sense. A name is a DNS domain, the thing every other system calls a domain. A claim is ownership of a domain and everything under it. A placement is the record that wires one exact domain to the site that serves it, and it is the one word that reads as nothing in particular: it does not say serving, routing or binding. Should the registry keep these words, and if not, what replaces them?

What depends on the answer

Every surface that shows the registry: the operator's Domains page and its three tables, the member's domain flows, the setup and hosting documentation, the model page, the registry's API names, and the issues written about any of them. The words in the code and the database can stay whatever they are; the question is what a person reads.

Options known so far

  • Keep the words and explain them where they appear.
  • Say domain wherever the code says name, on every surface and in every document, and keep claim and placement.
  • Rename placement as well, to a word that says what the record does, and decide whether the code follows the surfaces or only the surfaces change.

Decided when

The model page for the registry states the vocabulary a person sees and the vocabulary the code uses, with the mapping between them, and the surfaces and docs match it.

## The question The registry's vocabulary has three words a newcomer has to learn before the Domains page or its documentation makes sense. A *name* is a DNS domain, the thing every other system calls a domain. A *claim* is ownership of a domain and everything under it. A *placement* is the record that wires one exact domain to the site that serves it, and it is the one word that reads as nothing in particular: it does not say serving, routing or binding. Should the registry keep these words, and if not, what replaces them? ## What depends on the answer Every surface that shows the registry: the operator's Domains page and its three tables, the member's domain flows, the setup and hosting documentation, the model page, the registry's API names, and the issues written about any of them. The words in the code and the database can stay whatever they are; the question is what a person reads. ## Options known so far - Keep the words and explain them where they appear. - Say domain wherever the code says name, on every surface and in every document, and keep claim and placement. - Rename placement as well, to a word that says what the record does, and decide whether the code follows the surfaces or only the surfaces change. ## Decided when The model page for the registry states the vocabulary a person sees and the vocabulary the code uses, with the mapping between them, and the surfaces and docs match it.
cgalo5758 added the
kind
design
area/domains
labels 2026-09-21 07:18:12 +00:00
Author
Owner

An operator reading the Domains page for the first time should be able to tell a claim from a placement without the documentation. A claim is an organization's hold on a domain and the names under it; a placement is one exact name wired to the site that serves it. The page needs a concise definition of each, one line at most, where the words appear. Of the options above, explaining the words where they appear comes first; whether placement is renamed can be decided after.

This goes in before public launch, ahead of #35, because the words chosen here name that page's tabs.

An operator reading the Domains page for the first time should be able to tell a claim from a placement without the documentation. A claim is an organization's hold on a domain and the names under it; a placement is one exact name wired to the site that serves it. The page needs a concise definition of each, one line at most, where the words appear. Of the options above, explaining the words where they appear comes first; whether placement is renamed can be decided after. This goes in before public launch, ahead of #35, because the words chosen here name that page's tabs.
cgalo5758 added this to the Public launch milestone 2026-11-05 21:28:06 +00:00
Author
Owner

The question is wider than "placement". Renaming one word on one page would leave the rest of the vocabulary as inconsistent as it is now:

  • The kinds of holding read three ways. The operator Domains page says "Operator root", "Member" and "External"; the member's claims table says "Hosted" and "Custom"; the FedWiki sites tables say "Subdomain" and "Custom".
  • What a claim serves is "Placements" in the operator's live-claims column, "served names" in the placements section's count and search, and "Sites" on the member side.
  • The domain itself is "Domain" in most columns, "Name" in the placements table, "served name" in its search, and "root" in the policy card, the "Operator root" badge and the abandonment rules' "scope root".
  • The same outcome reads differently in core and in FedWiki. Core's verified-claim notice says "Any name inside it is yours"; FedWiki's says "Any subdomain of it is yours too".
  • The FedWiki create form's help says "workspace", a word ui-vocabulary keeps off reachable surfaces.
  • The docs (docs/models/domains-registry.md, docs/fedwiki-setup.md) use the code's words: claim, placement, operator_root, member, external.

This issue now covers the whole vocabulary. It asks which concepts a person meets (a domain held, a name served, the kinds of holding), what each surface calls them, and how those words map to the code's.

For launch, the Domains page keeps today's words and defines the two it depends on in its lead, as part of #35. This issue no longer blocks the launch.

The question is wider than "placement". Renaming one word on one page would leave the rest of the vocabulary as inconsistent as it is now: - **The kinds of holding** read three ways. The operator Domains page says "Operator root", "Member" and "External"; the member's claims table says "Hosted" and "Custom"; the FedWiki sites tables say "Subdomain" and "Custom". - **What a claim serves** is "Placements" in the operator's live-claims column, "served names" in the placements section's count and search, and "Sites" on the member side. - **The domain itself** is "Domain" in most columns, "Name" in the placements table, "served name" in its search, and "root" in the policy card, the "Operator root" badge and the abandonment rules' "scope root". - **The same outcome reads differently** in core and in FedWiki. Core's verified-claim notice says "Any name inside it is yours"; FedWiki's says "Any subdomain of it is yours too". - **The FedWiki create form's help** says "workspace", a word `ui-vocabulary` keeps off reachable surfaces. - **The docs** (`docs/models/domains-registry.md`, `docs/fedwiki-setup.md`) use the code's words: claim, placement, operator_root, member, external. This issue now covers the whole vocabulary. It asks which concepts a person meets (a domain held, a name served, the kinds of holding), what each surface calls them, and how those words map to the code's. For launch, the Domains page keeps today's words and defines the two it depends on in its lead, as part of #35. This issue no longer blocks the launch.
cgalo5758 removed this from the Public launch milestone 2026-11-06 07:26:29 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wiki-cafe/member-console#37