Most Powerful Open Source ERP

ERP5 Guideline Content Naming

Table of Contents

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