# Topic code

URL: https://tfw.how/model/topic-code/
Description: The four-character topic code: a two-character venture code and a two-character unit code that together identify one topic. Rules for codes, the shared venture, how to choose and change codes, how the code names every surface, and how venture, unit, and topic groups grant access.

A [topic code](/glossary/#topic-code) is a four-character code that identifies exactly one [topic](/glossary/#topic). Every surface of the topic is named with it. This page explains the form of the code, the rules for codes, and what the code defines.

The examples on this page use an invented venture called Example Co. Its names and codes are illustrations only.

## Form of the code

The topic code has the form `XXYY`:

- `XX`, characters 1 and 2, is the [venture code](/glossary/#venture-code). It identifies the venture.
- `YY`, characters 3 and 4, is the [unit code](/glossary/#unit-code). It identifies the unit.

A topic is one venture combined with one unit, so the two codes together identify exactly one topic.

| Topic | Venture code | Unit code | Topic code |
| --- | --- | --- | --- |
| Example Co Operations | `EX` (Example Co) | `OP` (Operations) | `EXOP` |
| Example Co MarCom | `EX` (Example Co) | `MC` (MarCom) | `EXMC` |
| Example Co Financial | `EX` (Example Co) | `FA` (Financial) | `EXFA` |

All topics of one venture start with the same venture code. All topics of one unit end with the same unit code.

## Rules for codes

- A topic code has four characters: two for the venture and two for the unit.
- Use the uppercase letters A to Z only. Do not use digits or other characters. The rule follows the project key rules of the task management tool, where the topic code is the project key, and letters-only codes also fit the identifier rules of most other tools.
- Write the code in uppercase, for example `EXOP`. Where a tool requires lowercase, such as a channel name, an email address, or a repository name, use the same letters in lowercase, for example `exop`.
- Each venture code is unique. No two ventures share a venture code.
- Each unit code is unique within the [registry](/glossary/#registry). A unit has one code, and that code is used in every venture that has the unit.
- Every venture code, unit code, and topic code is recorded in the registry. Look up a code in the registry before you use it. Never guess a code from the venture name or the unit name.
- A code is not reused. When a venture, unit, or topic becomes [inactive](/glossary/#inactive), its code stays recorded and is not given to anything else. Old records and surface names still carry the code, and reuse would make them point to the wrong topic.
- A topic code identifies a topic. It is not a type, a status, or a priority. Do not use it as a prefix to mean "this is a decision" or "this is urgent".

## How to choose codes

Choose a code once, when the venture or unit is first recorded in the registry.

1. Start from the canonical name. Use the first two letters, or two letters that a reader can match to the name. Example Co becomes `EX`. Operations becomes `OP`.
2. Check the registry. If the code is already used, or was used in the past, choose another pair of letters.
3. Avoid codes that are easy to confuse with an existing code, or that form a word that could be read as a status.
4. Record the new code in the registry with the canonical name before any surface uses it.

A new topic in an existing venture and an existing unit does not need new codes. Its topic code is the existing venture code followed by the existing unit code.

## Shared venture

A [shared venture](/glossary/#shared-venture) is a venture code for work that does not belong to one venture. It has two uses:

- **Work that spans several ventures.** For example, a contract with a supplier that serves every venture, or a financial report that covers all ventures.
- **Work whose venture is not yet known.** The work is kept in the shared venture until its venture is known. Then it is moved to the topic of that venture, and a link is left where it was.

The examples on this site use the invented code `XS` ("cross-venture shared") for the shared venture. Its topics follow the same rule as every other topic: `XSOP` is the shared venture's Operations topic, and `XSFA` is its Financial topic. Every surface of `XSOP` is named with the code in the same way as the surfaces of `EXOP`.

Everyone in the organization has access to the shared venture's topics. Do not put work in the shared venture that must stay inside the access boundary of one venture.

Use the shared venture only for these two cases. Work that belongs to one venture goes to that venture's topic, the [most specific valid topic](/glossary/#most-specific-valid-topic).

## When a code must change

Change a code only when it cannot be kept, for example when two ventures merge, or when a name change makes the code misleading. When a code must change:

1. Record the new code in the registry.
2. Keep the old code in the registry as an [alias](/glossary/#alias) of the same topic. Mark it as no longer used for new surfaces. Do not give the old code to another topic.
3. Rename each surface to the new code where the tool allows it. Where a tool cannot rename an identifier, such as a fixed project key, record that identifier as an alias.
4. Update the [topic profile](/glossary/#topic-profile) and the [purpose page](/glossary/#purpose-page) with both codes.

The topic does not change when its code changes. It keeps its owner, participants, records, and access boundary.

## What the code defines

The topic code is more than a label. Because every surface of a topic is named with its code, the code marks three things:

- **The topic.** Any record or surface with the code belongs to that one topic.
- **The access boundary.** The topic's [access boundary](/glossary/#access-boundary) is the set of people and automations that have access to its surfaces. Every surface with the code uses the same boundary.
- **The participants.** The [participants](/glossary/#participant) of the topic, and the teams they belong to, are the people who work in the topic. They are given access to the surfaces with the code through [access groups](#access-groups).

Access can then be granted and checked one code at a time. To see who works in a topic, list the members of the access groups that are granted access to its surfaces. To check access, compare the groups and members of each surface with the same code. A difference is a [provisioning gap](/glossary/#provisioning-gap), unless it is a deliberate exception that is recorded.

## Access groups

Access to a topic's surfaces is granted to [access groups](/glossary/#access-group), not to people one by one. There are three types of access group. They differ in how many topics they cover:

| Type | Members | Gives access to | Example name |
| --- | --- | --- | --- |
| [Venture group](/glossary/#venture-group) | Everyone who works across all units of one venture | Every topic of the venture: `EXOP`, `EXFA`, `EXMC`, and so on | `exampleco-venture` |
| [Unit group](/glossary/#unit-group) | Everyone who works in one unit, across all ventures | The topic of that unit in every venture: `EXOP`, `DWOP`, and so on | `operations-unit` |
| [Topic group](/glossary/#topic-group) | Everyone who works in one topic only | That one topic: `EXOP` | `exop-topic` |

The topic group is the most specific type. It is named with the topic code.

The three types are combined with OR: membership in any one of them grants access to the topic. A topic's surfaces are shared with the venture group of its venture, the unit group of its unit, and its own topic group. A person is added to the one group that matches the scope of their work, not to all three.

The same three group types exist in every system that controls access: the task management and knowledge base tool, the document storage tool, the password manager, and the chat tool. Each system has its own copy of the groups, with the same names and the same members, or uses groups that are synchronized from one directory. Access to a topic is then granted in the same way in every system.

Access groups are separate from the topic's email group. The email group, for example `exop@example.com`, is a mail address that delivers topic mail to its members. It is not used to grant access, even when the product allows it, because the people who receive the topic's mail and the people who have access to its files are not always the same.

### Example: who can see EXOP

Four people work at Example Co and Demo Works:

- Person A runs Example Co and works in all its units. Person A is a member of `exampleco-venture`.
- Person B is the operations lead for both ventures. Person B is a member of `operations-unit`.
- Person C works only on Example Co Operations. Person C is a member of `exop-topic`.
- Person D works only on Example Co MarCom. Person D is a member of `exmc-topic`.

The surfaces of `EXOP` are shared with `exampleco-venture`, `operations-unit`, and `exop-topic`. Person A, Person B, and Person C can see `EXOP`. Person D cannot. Person A can also see `EXFA` and `EXMC`. Person B can also see `DWOP`. Person C can see only `EXOP`.

## Surface names

Every surface of the topic is named with the topic code. The table shows the surfaces of two topics in the same venture. Each [tool class](/tool-classes/) page gives the naming pattern for its class, and each [tool](/tools/) page shows how to set it up in one product.

| Tool class | Surface | Example Co Operations (EXOP) | Example Co MarCom (EXMC) |
| --- | --- | --- | --- |
| [Task management](/tool-classes/task-management/) | Project and key | Example Co Operations, key `EXOP` | Example Co MarCom, key `EXMC` |
| [Knowledge base](/tool-classes/knowledge-base/) | Space and key | Example Co Operations, key `EXOP` (or space alias `EXOP`) | Example Co MarCom, key `EXMC` (or space alias `EXMC`) |
| [Document storage](/tool-classes/document-storage/) | Shared drive | `EXOP - Example Co Operations` | `EXMC - Example Co MarCom` |
| [Document storage](/tool-classes/document-storage/) | Top-level folder | `Contracts EXOP - Example Co Operations` | `Contracts EXMC - Example Co MarCom` |
| [Chat](/tool-classes/chat/) | Chat channel | `exop-exampleco-operations-chat` | `exmc-exampleco-marcom-chat` |
| [Chat](/tool-classes/chat/) | Automated channel | `exop-exampleco-operations-automated` | `exmc-exampleco-marcom-automated` |
| [Email](/tool-classes/email/) | Email group | `exop@example.com` | `exmc@example.com` |
| [Email](/tool-classes/email/) | Label | `EXOP` | `EXMC` |
| [Calendar](/tool-classes/calendar/) | Shared calendar | `EXOP Example Co Operations` | `EXMC Example Co MarCom` |
| [Calendar](/tool-classes/calendar/) | Event title prefix | `EXOP:`, for example `EXOP: Weekly review` | `EXMC:`, for example `EXMC: Weekly review` |
| [Code repository](/tool-classes/code-repository/) | Repository prefix | `exop-`, for example `exop-website` | `exmc-`, for example `exmc-campaign-pages` |
| [AI agent workspace](/tool-classes/ai-agent-workspace/) | Project or workspace | `EXOP Example Co Operations` | `EXMC Example Co MarCom` |

Pages for specific products: [Jira](/tools/jira/) (project key), [Confluence](/tools/confluence/) (space key), [Google Drive](/tools/google-drive/) (shared drive), [Slack](/tools/slack/) (channels), [Gmail](/tools/gmail/) (group and label), and [Google Calendar](/tools/google-calendar/) (calendar and event titles).

The shared drive and its top-level folders put a hyphen between the code and the canonical name. The other surfaces keep the forms in the table.

If a tool cannot use the code, for example because a key is already taken, record the name it uses as an alias of the topic.

## Example: deciding access with the code

A new person joins Example Co and will work only in Operations.

1. The owner of Example Co Operations adds the person as a participant of the topic `EXOP` in the topic profile.
2. The person is added to the topic group `exop-topic` in each system that controls access. Because every `EXOP` surface is shared with `exop-topic`, the person now has access to the `EXOP` project, the `EXOP` space, the `EXOP - Example Co Operations` shared drive, both `exop-` channels, the `EXOP` folder in the password manager, the shared calendar, the `exop-` repositories, and the `EXOP` AI agent workspace.
3. If the person handles topic mail, they are also added to the email group `exop@example.com`. This gives no access to other surfaces.
4. The person is not added to `exampleco-venture` or `operations-unit`, because they do not work across all of Example Co or across the Operations unit of every venture. They have no access to `EXMC` or `DWOP`.

When the person later also works in MarCom, the owner of Example Co MarCom adds them as a participant of `EXMC`, and they are added to `exmc-topic`. If they later work in every unit of Example Co, they are added to `exampleco-venture` and removed from `exop-topic` and `exmc-topic`, which no longer add access. When the person leaves, they are removed from each group. Because every surface is shared with the same groups, one change in each system changes access to every surface.

## Common mistakes

- **Guessing a code.** A code that looks right may belong to another topic, or may not exist. Look it up in the registry.
- **Reusing an old code.** Old records still carry it. Choose a new code.
- **Different codes in different tools.** If the project key is `EXOP` and the shared drive is named `EXOPS`, a search for the code misses the drive. Use one code, or record the other identifier as an alias.
- **Granting access one surface at a time.** Access that is granted only where a person asked for it differs between surfaces. Grant access through the access groups, which are shared with every surface with the code.
- **Adding people to individual surfaces.** A person added directly to one drive or one channel is outside the groups, and the access is not reviewed with them. Add the person to the venture group, the unit group, or the topic group that matches their work.
- **Using the email group as the access group.** The email group decides who receives topic mail. Use the access groups to decide who can see the topic's surfaces.