Naming Conventions and Documentation for Internal Tools

Open the views list in a tool that’s been live for a year and you’ll often find something like this: “All Orders”, “All orders NEW”, “Orders - Sam”, “orders open (use this)”, “Copy of Open Orders 2”. Somewhere among them is the view the operations team relies on. Nobody is sure which.

Names are the cheapest documentation you have. Get them right and much of the tool explains itself. Get them wrong and every new hire has to be walked through it by the one person who remembers.

Why naming matters more than it seems

In a spreadsheet, a confusing column header affects one tab. In an internal tool, names show up everywhere: forms, filters, reports, automations, exports and integrations. People search by them, and automations reference them.

A few illustrative costs of poor naming:

• A new starter spends their first week asking which field is the “real” due date.
• Two reports disagree because one uses “Value” and the other uses “Amount”, and they mean different things.
• Someone deletes “Copy of Open Orders 2”, which turns out to feed a weekly leadership dashboard.

None of these are dramatic. Together they add up to a tool that feels untrustworthy.

Conventions for tables, fields and views

You don’t need a long rulebook. A half-page of conventions, applied consistently, is enough. Here’s a starting set you can adapt.

Tables (the main collections of records, like orders or customers):

• Use plural nouns: “Orders”, “Customers”, “Site Visits”.
• Name the thing, not the process: “Purchase Requests”, not “Purchasing Workflow”.
• Use the words your business uses. If everyone says “jobs”, don’t call the table “Work Orders”.

Fields:

• Use plain, specific words: “Requested Delivery Date”, not “Date 2” or “RDD”.
• Put the unit or type in the name where it helps: “Weight (kg)”, “Discount (%)”.
• Start yes/no fields with a verb or “Is”: “Is Urgent”, “Requires Approval”.
• Name link fields after the thing they link to: “Customer”, “Assigned To”.
• Avoid abbreviations unless everyone in the company already uses them.

Views:

• Lead with the audience or purpose, then the filter: “Warehouse – Ready to Pick”, “Finance – Awaiting Invoice”.
• Mark personal views with the owner’s name, and keep shared views free of names.
• Never leave “Copy of…” in a shared view name. Rename it or delete it.

Agree the set once, write it down, and apply it to anything new from today. Rename old things gradually, following the approach in “Changing a Live System Without Breaking Trust”, because renames can break views and automations.

One concept, one name

The most damaging naming problem isn’t sloppiness; it’s two names for one thing, or one name for two things.

Say sales calls a customer’s first order the “start date”, operations calls it the “go-live date”, and finance uses “start date” to mean the contract start. Put all three in one tool without resolving that and you’ll get confident, wrong reports.

Before you finalise a field, ask: does another team already have a word for this? Does this word already mean something else here? Settling it takes a 20-minute conversation. Not settling it takes years of confusion. Post 73, “Merging Spreadsheets From Multiple Teams Into One System”, covers the harder political version of this.

A data dictionary people will read

A data dictionary is a list of your fields with a plain-English explanation of each. It sounds bureaucratic, but a short one is one of the most useful things you can give your team.

The trick is keeping it small and close to the work. A long document in a forgotten folder will be out of date within a month. Better options:

• Use the description box on each field, if your platform has one. Many show it as a tooltip on forms, which is exactly where people need it.
• Keep a simple table inside the tool listing each important field, if you need more than tooltips allow.

For each field, capture just enough:

The “not to be confused with” column is the one people thank you for. Don’t document every field. Start with the 15 or 20 that matter most or cause the most questions.

Document the process, briefly

Beyond fields, people need a short explanation of how the tool fits the work. One page is usually enough:

• What the tool is for, and what it isn’t for
• The main states a record moves through, and who moves it
• Which views each role should use day to day
• Who the business and technical owners are
• Where to request changes or report problems

Link it from inside the tool, ideally from the place people land when they log in. Pair it with the approach in “Training Users Without a 40-Page Manual” rather than writing a manual.

Keeping it current

Documentation decays unless updating it is part of making changes. Add one line to your change process: “Update field descriptions and the process page if affected.” Make it the technical owner’s job, and check it during the monthly review.

Once a quarter, skim the views list and delete or rename anything that breaks the conventions. Ten minutes is usually enough.

Where to start this week

1. Write a half-page naming convention for tables, fields and views, and share it with anyone who builds in your tool.
2. Clean up the shared views list, removing “Copy of…” names and duplicate views, after checking nothing depends on them.
3. Add descriptions to your 15 most important fields, including a “not to be confused with” note where relevant.
4. Draft a one-page process summary and link it from the tool’s landing page.