Crime
Introduction¶
This guideline defines the naming conventions used for ERP5 documentation and documents related to Nexedi stack in general. Defining a naming convention for documentation or for corporate documents may seem awkward. However, as soon as a group of people work on the same set of documents within a company, within a community or accross communities and companies, they start exchanging documents. It is quite frequent to see engineers exchanging documents named "Untitled-3.doc" or "Offer.xlsx" and wondering after some time what was this document, in which version and where was the translated version in a certain language.
By defining very precisely and once for all how all documents should be named, this common problem can be solved no matter which document management system everyone uses and no matter how documents have been shared: by email, through the Web, using a real time collaboration editor.
We will define below the general ideas that should be adopted for ERP5 documentation with some examples. Afterwards we will provide a precise reference of rules to follow, recommendations and crimes with patterns to avoid.
General Principles¶
All documents should be named according to the following principle:
- First a Reference representing the project (ex. P-JIO), group or publication section a document is related to.
- Then a Document Name (ex. Design.Document) which represents a document name or title.
- Then a Version number (ex. 001) (added automatically)
- Then a Language (ex. en) (added automatically)
- And at the end an Extension in relation with the MIME type (ex. .odt) (added automatically)
Examples:
- P-BAOBAB-Design.Document-001-en.odt
- NXD-Operation.Rules-001-en.odt
- erp5-solution-overview-001-en.html
Rule¶
#Business Reference Is An Uppercase Id And Number Sequence Separated By Hyphen¶
Some business documents used commonly at Nexedi can benefit from a better
naming of their reference. Such documents are often referenced in mails,
emails, conversations, etc. They include invoices, purchase orders, sales
orders, etc. The naming convention for such references is based on 2 letters
followed by a sequence of numbers combined if necessary with a date. Most of
the times these business references are generated automatically.
Business References are generated automatically.
Good Examples:
PO-1234567 (Purchase Order)
SO-1234567 (Sales Order)
IN-1234567 (Sales Invoice)
SPL-123456 (Sales Packing List)
IPL-123456 (Internal Packing List)
PPL-123456 (Purchase Packing List)
Bad Examples:
Sales-Order-123456
Invoice-2015-12-12
PurchasePL-1234
#Document Name Is Camel Case And Dot Separated¶
Document names must be written in camel case using dots to separate word (no space - used in URL).
Please also camel case all names, so ERP5 -> Erp5 to distinguish
between anchor reference and document name.
Good Examples:
Design.Document
Operation.Rules
Thalys.Head.Logo
ERP5-Guideline.Things.To.Avoid.In.Erp5
Bad Examples:
Design-Document
Operation Rules
ERP5-Guideline.Things To Avoide In ERP5
#Document Name Must Use Anchor, Reference, Name, Version, Language And File Type¶
All documents must consist of the following parts (in the order listed):
- Anchor and
- Reference representing a project (ex. P-JIO), group or the publication section a document is related to.
- Document Name (ex. Design.Document) which represents a document name or title.
- Version number (ex. 001).
- Language (ex. en).
- File Extension in relation to the MIME type (ex. .odt).
The generic format for a reference is:
[Anchor-Reference]-[Dotted.Document.Name]-[Version]-[Language].[Mimetype]
Good Example:
P-BAOBAB-Design.Document-001-en.odt
NXD-Operation.Rules-002-en.odt
erp5-Solution.Overview-001-de.html
Bad Example:
MyFile.html
How-To.Do.Something.html
Document123.js
This naming convention applies to documents stored as files. Documents stored in ERP5 DMS (document management system) do not require language, version and file extension in the reference, because these will be managed automatically by ERP5.
A document will be stored like this:
Reference: P-BAOBAB-Design.Document
Version: 001
Language: en
Portal Type: Text (read-only)
So when creating document name, leave away the aforementioned parts.
Good Example:
P-BAOBAB-Design.Document
NXD-Operation.Rules
erp5-Solution.Overview
Bad Example:
mySample-001-en.odt
NXD-Operation.Rules-002-en.odt
#Group Reference Is Uppercase And Uses Category Value¶
Group references must be upper case and use the reference value of the
appropriate category. There is no suffix. Abbreviations are allowed (?).
Reference values are defined once during category configuration. It is
therefore essential to review categories of
Nexedi ERP5 Corporate Categories to
have the correct options available from the beginning.
Good Example:
NEXEDI
HQ
Bad Example:
Nexedi
Headquarter
#Image Uses Publication Section As Anchor Reference¶
All images should follow the same consistent naming scheme used for documents with the restriction of the reference only being allowed to be a publication section.
- CamelCase
- Dot Separator
- Format: [Anchor-Reference]-[Title.With.Dots]
Good Examples:
NXD-Documentation.Screenshot.Content.Authoring
erp5-graphic.official.logo
Bad Examples:
documentation.graphic-authoring.Screenshot
#In Document Name Publication Section Is Written In Camelcase¶
Publication Sections with multipe words such must be written
in camel case.
Good Examples:
TechnicalNote
HowTo
Bad Examples:
Technical-Note
How.To
How-to
how-to
howto
#Language Is Abbreviated As Two Lowercase Characters¶
In document names, language is always written in lowercase using two characters
and following the
international standard (ISO 639-1).
Good Examples:
en
fr
pt
Bad Examples:
EN
English
#Project Reference Uses A Suffix And Character Sequence Separated By Hyphen¶
Project/Ticket References should be named according to the following principle:
- A Suffix letter in uppercase (ex. P for project)
- then a hyphen,
- followed by a sequence of letters in upper case (ex. BAOBAB)
Suffix letters are associated to portal types:
- P for Project
- S for Support Request
- O for Sales Opportunity
- C for Campaign
- M for Meeting
Project and Ticket references are entered by the user and, if possible,
validated by workflow to guarantee unicity.
Good Examples:
P-BAOBAB
O-ADIE
S-12345
C-EXPRESS
Bad Examples
PROJECT-BAOBOA
O-AIDE-ET-ACTION
S-Client-12345
Campaing-Express
#Publication Section In Document Name Is Separated By Hypen And Lowercase¶
References of publication sections are derived from their short title and
should map to the publication section tree. They should use small caps with
hyphens to separate words. (?) Besides the use of small caps and the requirement for
uniqueness of a reference accross all publication sections, no other convention
exists. Publication Section references are configured once at category configuration time.
Good Example:
erp5-solution
express-hosting
NXD-marketing
Bad Example:
administration
marketing
#Reference Anchor Is Uppercase And Uses Group, Project, Publication Section Or Business¶
Associating appropriate references to ERP5 documents is required to implement
document naming in a useful way. With an appropriate naming convention, it
becomes possible for a document to reference an ERP5 document in full text.
For example the word INV-3762546 can be recognised as a Sales Invoice and
associated automaticaly to create relations between an email and an invoice
in ERP5.
We distinguish 4 kinds of references:
- References of group using the reference value of the appropriate cateogry (ex. NEXEDI).
- References of project/ticket for document follow-up. This is the primary approach for document naming that should be followed in Nexedi (ex. BOABAB).
- References of publication sections for document publication without follow-up. This is the primary approach for naming marketing documents and topic-based knowledge sharing (ex. RECRUITING, MARKETING).
- References of business documents. Conventions are introduced here to distinguish different types of documents (ex. invoices, orders, may be automatically generated) and allow the creation of links between text and objects within ERP5 (ex. 12345).
Good Examples:
P-BAOBAB
O-ADIE
P-NEXEDI
NXD-MARKETING
S-12345
C-EXPRESS
Bad Examples:
P-Press-Release
O-Document
S-DRAFT-Letter
#Version Number Is Ascending And Use Three Digits¶
Version number uses 3 digits (0 to 9) only (NO letters, dots or commas)
and it should be increased in 1.
Good Examples:
001 -> 002
002
003
Bad Examples:
03a -> 03b
1b
Crime¶
#Reference Should Never Use Arbitrary Numbers Or Abbreviations¶
No arbitrary numbers and abbreviations (not self explanatory) should be
used in document references.
Bad Examples:
user-My.Document.1
user-My.Document.smth