Table of Contents

• Introduction
• Recommendation
  • Document Should Have Explicit Predecessors And Successors Defined
  • Documentation Document Should Have License Specified
• Rule
  • Document Title Uses Capitalized Keywords Prefixed By Publication Section
  • Documentation Document Anchor Uses Software And Publication Section Split By Hyphen

Introduction¶

Modules are one of the core components of ERP5 and usually the ones most development in ERP5 focusses around. It is therefore important that a clear set of conventions are maintained ensuring the modules are created or extended in a consistent and portable way.

Recommendation¶

Document Should Have Explicit Predecessors And Successors Defined¶

ERP5 provides an explicit (you declare manually) and implicit (used internally) way to cross-reference related documents. Related documents can be:

• Predecessors - the current document is linking to the related document
• Successors - the current document is linked from the related document
• Similar Documents - documents with similar content

Please make use and explicitly add related documents to improve the quality of the overall document and documentation structure. This might at some point also be done automatically based on links placed in a document.

Applicable/Referenced documents are only used in internal documents and have separate guidelines. At some point they should be merged with successor (referened) and similar (applicable) documents.

Documentation Document Should Have License Specified¶

Every document visible to the general public should eventually have a licence, defining the scope to which a document can be used outside of the scope of Nexedi.

Documents which explain how to do something will be made available under GFDL license while documents that explain why are CC-NC-SA. The differences are explained here.

Rule¶

Document Title Uses Capitalized Keywords Prefixed By Publication Section¶

Document Titles will be used on links and table of contents as well as auto generated tables. They should also work standalone and be self explanatory (compared to the short title, which is missing context (eg. Publication section). Use capitalized keywords for the title and prefix it by the documentation publication section.

Good Examples:

Guideline on Authoring Content
How To Create A Documenation Document

Bad Examples:

Create Property Sheet
Create a property sheet

Documentation Document Anchor Uses Software And Publication Section Split By Hyphen¶

Anchor references are more restricted when creating documentation documents than when naming generic content. The anchor must be a lowercase software product (like "erp5" or "slapos") followed by a hyphen and a documentation publication section. Multi word publication sections are written as single Camelcase word

Good Examples:

erp5-HowTo
slapos-TechnicalNote
erp5-Tutorial

Bad Examples:

SlapOS-how-to-create-property-sheet
ERP5.HowTo.Create.Property.Sheet