Topic code

A topic code is a four-character code that identifies exactly one 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. It identifies the venture.
• YY, characters 3 and 4, is the unit code. It identifies the unit.

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

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. 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, 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 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.

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 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 and the 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 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 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 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, unless it is a deliberate exception that is recorded.

Access groups

Access to a topic’s surfaces is granted to access groups, not to people one by one. There are three types of access group. They differ in how many topics they cover:

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 page gives the naming pattern for its class, and each tool page shows how to set it up in one product.

Pages for specific products: Jira (project key), Confluence (space key), Google Drive (shared drive), Slack (channels), Gmail (group and label), and 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.