Naming things
User needs
Users should to be able to infer a basic understanding of what a given thing does from its name.
Principles
Names should be self-descriptive – you should be able to infer a basic understanding of what something does from its name.
Avoid naming things using puns, uncommon acronyms, version numbers, or with a brand. All of these make it difficult for others to understand what the thing does. Puns and acronyms (unless they’re very widely understood outside government, like API) probably won’t be understood by anyone coming to your thing later. Version numbers and brand names (including names of parts of government) are likely to change over time as the thing adapts to changing user needs and policies.
If your service is an instance of a well-known type of system (like an intranet or help desk), it is appropriate to include the name of the government body it’s associated with so people can understand the context it applies to. Where possible, avoid exposing that name to people (usually citizens or organisations outside government) who shouldn’t have to understand how government is structured to do what they’re trying to do.
Ensure you use the same name consistently whenever you’re referring to the same thing. For example, in most cases the name of an application’s GitHub repository should match its hostname. Similarly, the team responsible for an application should probably be called something related to the application and its GitHub repositories.
Examples
These applications are well named as they communicate their purpose reasonably clearly:
- Find postgraduate teacher training
- Apply for postgraduate teacher training
- Teaching Vacancies
- Buying for schools
The names of these applications are ambiguous and possibly confusing:
- DTTP (Database of Trainee Teachers and Providers)
- GiTIS - Get into teaching information system
- DQT - Database of qualified teacher
- Sirius
- Common Platform
Conventions
Use hyphens in GitHub repository names, not underscores. This reflects the practice of naming the repository to match the service name and domain.
Git branch names should also use hyphens as a word separator.
Separate words in file names with underscores.
Other resources
The service manual has good guidance for naming services, a lot of which will also be relevant when naming applications or packages.