Table of Contents
Introduction¶
The following conventions define the way documents should be created for the ERP5 documentation and beyond. They cover both the actual content as well as metadata required to be defined on a document. It only introduces document naming conventions which is covered in detail with separate guidelines.
General Principles¶
- We write in English (UK), other languages depending on demand.
- Always use a spellchecker (like Languagetool).
- All documentation documents will be created as Web Pages (or Test Pages).
- All documents are written in HTML5.
Rationale¶
Why Conventions On Content?¶
Writing documents is not that much different from producing code. As long as you write code for yourself, your style of coding does not matter. But once multiple developers collaborate on a project, conventions become important to ensure code interoperability and every contributor being able to quickly understand each others code. The same applies to documentation and documents in general: conherent and understandable documentation from multiple contributors are only possible when certain conventions are being followed.
Why HTML5?¶
As with code where our timeframe goes beyond the lifespan of fashionable frameworks we also try to create lasting content. HTML has been around for more than 20 years, is more or less ubiquitous and brower-focussed. It therefore aligns with our overall browser-centric mindset to also create HTML5 based content instead of using one of the many markup dialects, that are frequently changed, not interoperable and require server rendering to eventually also output HTML.
We also define strict conventions for how HTML can be used. The documents written should be pure, raw content with only basic HTML5 tags. This allows multiple renderers to display the content in various forms - think of slideshows, chapters or embedding in web sites, each taking the raw content, enhancing it in some sort of way, adding layout and displaying the content in various forms. Creating content this way ensure it will persist, even as renderers evolve over time.
Naming Conventions¶
Document names (the reference field) should follow the guidelines defined for document naming. In a nutshell, the format for references is:
[Anchor-Reference]-[Dotted.Document.Name]-[Version]-[Language].[Mimetype]
The following additional restrictions apply specifically for documentation documents:
- [Anchor-Reference] can only be a lowercase product, such as "erp5" combined with publication section, separated by hyphen.
This way it is clear from the reference which software a document belongs to. Keep in mind, the reference will be in the URL, so it should meaningful. Also when creating a new version of a document, always perserve its original reference.
${predicate_view_as_book}