How to name it?
Nomenclature is one of the major problems both for authors of all kinds of documents, files, folders, diagrams, etc. but, above all, for their recipients. Naming is extremely often the cause of many problems and misunderstandings among people cooperating both within project teams and entire enterprises.
The solution is to introduce a unified naming system that allows you to quickly find the data you need, instantly recognize the contents of a file or folder, avoiding the extra work caused by the use of an outdated document.
Our guide presents you with useful practical aspects of onomastics, based on linguistic studies and business experience. We also provide you with a document naming system that is ready to be implemented in your company.
Suggested naming rules
There is no one generally accepted convention. Depending on the company’s or individual’s needs, different solutions are introduced. Below, we present you our proposition of the rules for naming depending on the type of the named object.
Podsumowując, o ile w każdym języku wymienione desygnaty: stół, drzewo, pies, kobieta, człowiek, będą miały odmienne brzmienie i zapis, o tyle nazwy własne w każdym języku pozostaną w tej samej postaci (pomijając ewentualne różnice wynikające z adaptacji fonetycznych i morfologicznych).
We propose the following convention for naming projects:
[Company name/product] – [Details]
- Craftware – Technical Writing
- SFDC – Service Cloud
- Safari – SFDC Implementation
We offer options depending on the needs and business context for naming files and documents:
[Project name] – [Document name] DD-MM-YYYY
[Project name] – [Document name] X.X
[Name of the System] [Release number] – Name of the document X.X
[Name of the System] [Release number] – Name of the document YYYY-MM-DD
- Pakmex – Workshop note 2018-05-18.docx
- CraftPol – Training Materials 2.0.pptx
- Zinder Release 2.0.0. – Functional Specification 2.1.docx
Naming classes, methods and variables
Following the recommendations of Salesforce, we recommend using the following Java standards:
Class names should begin with a capital letter and should not contain spaces or underscores. If they consist of several words, each word should begin with a capital letter. The names should be significant.
Methods should start with a lower-case verb. If they consist of several words, each subsequent word should begin with a capital letter. The method names should be significant.
The names of variables should be significant.
Naming diagrams, charts and graphics for documentation needs
Each diagram, chart and graphic should have a name. The caption should be left-aligned and under the diagram or graphic. We recommend the following convention:
Figure. Mockup design
Diagram. Regional revenue
Naming diagrams, charts and graphics in the catalog
Create a separate catalog for all graphics, name it e.g. images.
Each graphic is named according to the formula:
diagram [description] [version number]
figure [description] [version number]
[general description] – [detailed description] [version number]
Naming requirements, ID numbers and reference names
ID numbers of requirements
Requirements in documents must be numbered to enable their identification. In our proposal, the requirement’s ID consists of the abbreviation of the project name, category and consecutive number.
MON-US-001 – User Story in the MONSTARI system
MON-REQ-001 – Requirement in the MONSTARI system
MON-UC-010 – Use Case in the MONSTARI system
MON-SCR-023 – Screen in the MONSTARI system
MON-BR-002 – Business rule in the MONSTARI system
MON-DS-001 – Technical description of functions in the MONSTARI system
ID numbers of documents
All documents related to a given project should have an assigned ID number. If possible, use the ID provided by EDMS (Electronic Document Management Systems), for example, the ID assigned in the Project Library. The ID must be visible on the title page of the document and in the header and footer on each subsequent page.
ID format of documents
The ID can be in one of two formats:
- SystemDocID – assigned by EDMS, e.g. PL ID 11788999
- ORG_TYPE_n – assigned manually if documents are not kept in EDMS. ORG is the organization issuing the document, TYPE is the abbreviation of the document, n is the consecutively assigned number.
When you want to send the reader back to another document, you should give its ID number, and the link to the document should be just additional information.
Why is it worth using a naming convention
Thanks to the naming convention, files in folders are organized in chronological order. What’s more, just look at the file name to get an idea of what it’s about.
The naming convention should be tailored to the needs of your team. There is no ideal convention, but there are a few basic rules to follow.
Additionally, you should use clear abbreviations and document your decisions based on which components will be used (for example [project name] – [project type]), what is the correct record (for example DOE Project Implementation.docx), and what the acronyms means (DOE means Department of Energy).
As the files will be grouped on the basis of the first few components, the elements of the name should be listed in order from the more general to detailed. Additionally, it is worth using the year-month-date format (YYYY-MM-DD) to make the files display in chronological order.
What should I do to make the naming system work?
It is crucial that all the employees of your company understand the naming method and use it conscientiously. We hope that our guide will help you implement a unified, understandable naming system in your company. If you have any additional questions, please do not hesitate to contact us.