Naming things in B2B SaaS

May 3, 2024

Engineers love giving things ambiguous, technical names like task, workflow, record, definition. They also love combining these names into new ones like task_definition or workflow_configuration or even task_definition_configuration. Unfortunately, I've seen a task_definition_configuration_definition in the wild. As an engineer, I'm guilty of the above as well.

But it's confusing for your end users, especially if they're business end users. If I'm an accountant, I don't know what a workflow or workflow_configuration is. I also don't want to learn your app specific terms. Every app uses some variation of these ambiguous terms and it's cognitive overload. But accountants do know what a "Book of Accounts" or "Journal Entry" is.

Instead of using ambirous technical names, think twice about the domain of your end user and about what you're really trying to model.

Some database table names to avoid:

  • task
  • workflow
  • record
  • object
  • definition
  • configuration