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.
Recommendation¶
#Beware of Editor Autoformat¶
Be careful when editing web pages using editors that autoformat the underlying HTML.
For example, the FCK Editor version on Nexedi ERP5 (outdated) will line breaks
added in the HTML content, so text blocks and also code snippets will be
reduced to a single line.
Other editors are OK, but you should prefer a raw text editor to write in HTML
to have maintainable text — it will help you a lot when you will have to
update your page.
#Content Should Be Served By Cdn If Anonymous¶
Nexedi should have a common CDN (64 thread zope backend configured
to serve ONLY anonymous content that can be HTTP cached).
#Content Should Be Served Using Asset And Blob Subdomains¶
Besides utilizing: cdn.nexedi.com (https)
every web site should
have the following dedicated subdomains:
/asset
(16 thread zope)
/blob
(64 thread zope)
#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.
#Document Should Have Follow-Up Defined¶
If a document is used to generate an export (chapter) containing data from
other objects, such as:
- Sale Offer
- Sale Order
- Sale Opportunity
- Project
these must be declared in the document follow-up. Note, that
you only need to reference a single follow-up, for example the Sale Order
and not this Sale Order's Requirements.
#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.
#External Link Should Have Target Attribtue Specified¶
It is good practice to use the target="_blank"
attribute on links
pointing to external pages. We might add this automatically at some point but
for now add it manually if it important for users to remain on the page
they are on.
Good Example:
<a target="_blank" href="www.google.com">Search</a>
Bad Examples:
<a href="www.google.com">Search</a>
#Image Should Have Publication Section Defined¶
If applicable, add one of the following publication sections to images. This
will help making images more easy to find inside ERP5 as the overall volume
of images grows.
- Design/Graphic/Flowchart
- Design/Graphic/Image
- Design/Graphic/Logo
- Design/Graphic/Screenshot
#Link Title Should Be Defined On Documentation Document¶
Title attributes are technically not required and only marginally search engine
relevant compared to alt attributes on images which are important. Still, it
is good practice to put titles on links, even more so when creating content for
exports/chapter views, where link titles will be used for the tables of applicable and
referenced documents. At some point internal links should have a title set
automatically so only titles on external documents have to be set by hand. But
until then please put titles on links if you want to export a document later on.
Good Example:
<a title="ERP5 HowTo - Put Titles On Links" href="erp5-HowTo.Put.Title.On.Links">;Put titles on link</a>
Bad Examples:
<a href="erp5-HowTo.Put.Title.On.Links">Put titles on links</a>
#Web Section And Exportable Document Should Have Short Title Specified¶
For internal documents the short title is not compulsory so there is no
requirement to provide a short title. The following exceptions exist:
- Sale Offer/Sale Order: the short title is used on the cover page
- Web Section: the short title is used in breadcrumbs
Rule¶
#Use gender neutral writing in documentation¶
We should not expect that all ERP5 users are male or female. When you want to refer to a user doing something, please use a neutral way of refering to the user - and neutral is not "it"...
Good Examples:
The user should click on the link.
He/She should click on the link.
They should click on the link.
Bad Example:
He should click the link.
She should click the link.
It should click the link.
#A Documentation Document Must Have Group And Classification Defined¶
All documentation documents must have Classification¶ set to
Collaboration Team/Staff and Group¶ set to Nexedi.
Note that without explicitly setting a group you may not be able to change
a documents workflow state (can't publish for example).
#A Link Between Internal Documents Uses A Relative Url¶
We can distinguish between absolute, path and relative links.
Absolute Links¶
Pros:
- increase number of entries in cache, bloats cache
- beneficial for search engine optimization
- allows for dedicated zope "threading" of resources by domain
Cons:
- incompatible with restricted site access
- reduces portability from one website to another
Path Links¶
Pros:
- minimizes number of entries in cache
- compatible with restricted access on one site
- ensures content portability from one website to another
Cons:
- disadvantageous for zope "threading" resource utilization per domain
- inferior for search engine optimization
Relative Links¶
Pros:
- minimizes number of entries in cache
- compatible with restricted access on one site
- ensures content portability from one website to another
Cons:
- reduces ability to cache
- inferior for search engine optimization
- disadvantageous for zope "threading" resource utilization per domain
Because we favour security and content portability, links from one
HTML content to another HTML content should be relative link except
link to content that only makes sense in a given context, for example an
absolute lnk for a Nexedi press release which should be displayed on a
Nexedi website.
Good Example:
<a href="erp5-HowTo.Put.Title.On.Links">Put titles on links</a>
Bad Examples:
<a href="http://www.erp5.com/documentation/devleper/erp5-HowTo.Put.Title.On.Links">Put titles on links</a>
#A Screeshot Displays Full Screen Without Bars¶
To have a consistent format always use a FULL screenshot without bottom bar but without the url bar.
Bad Examples:
This is a full browser screenshot. The bottom bar and everything above the
url bar should be cropped.
Good Example:
Bad Example:
To ensure easy layouting on all print formats, the documentation should include
no cropped to fit screenshots showing just snippets of code. Either use a <code>
</code> for displaying code or supply a full browser screenshot.
#Abbreviation Link Title Must Contain Abbreviated Text And Description Split By Semicolon¶
Abbreviations link titles contain the full abbreviation title ("AI" would be "Artificial Intelligence") as well as an description of what this means. The link to a resource is optional.
Good Examples:
... enterprise resource planning [<a href="https://en.wikipedia.org/wiki/Enterprise_resource_planning" title="Enterprise Resource Planning;Description">ERP<a>]
#A Code Snippet Uses Code Tag Wrapped In Pre Tag¶
Code sections always use <pre><code>Your code</code></pre>
(there are
many sections the other way around, please update if you find one).
We are using HighlightJS, because it
should detect languages automatically (else add a class="[language-miniscule]"
to the code tag) and was
easy to extend to show line numbers and custom coloring. Currently we only
added support for Python, CSS, HTML, XML, JavaScript, SQL and JSON. Please let me
know if you want additional languages to be included. Also note that
HTML markup must be escaped inside <code> blocks (use Textmechanic to quickly escape larger code blocks).
#Document Content¶ Is Written In British English¶
All documents must be written in English (British Englsh). Other languages only
depending on demand.
All script names, portal_types names, form names, field names, workflow state
names, etc. should also be written in "British English" and will be translated
into other languageswith the Localizer tool.
Good Examples:
Organisation
Organisation
Bad Example:
OrganiZation
Société
The user interface has to be "business oriented" and localisation work of the
user interface has to be easy ERP5 technical vocabulary should be banished from the user interface.
Good Examples:
Shipping Date
Customer
Bad Examples:
Start Date (on packing list)
Destination Section (on a sale order)
#Document Content¶ Is Written In HTML5¶
All content must be written in HTML5. No other formats such as markdown are permitted.
#Document Keywords Are Lowercase Singular And Line Separated¶
One of the most important fields to define are keywords, because they help showing
related topics or searching for keyword related documents. Keywords allow us
to structure the large amount of documentation documents into useful groups. To
not end up with a million keywords, the following rules must be followed:
- One keyword per line, no commas
- Names can be mixed case, like ERP5, MySQL, Senna
- All other keywords are lowercase
- All keywords are singular
- Seperate words by space, nothing else
- Publication sections are NOT keywords
- Follow-Up¶ Products (like ERP5, SlapOS, etc) are NOT keywords
Good examples:
search
portal catalog
MySQL
These are helpful keywords. ERP5 is defined to not mix with other software
solutions, search will return this document for all users looking for
information on searching in ERP5. portal catalog is written without underscore
("_") and MySQL as a name can be written in mixed case.
Bad examples:
ERP5,
documentation,
HowTo,
portal_skins,
modules,
ERP,
Open Source
Commas will become part of the keywords, defining documentation
will make all other documentation documents show up as related documents. HowTo
is mixed case without space as separator and like documentation defined
in publication_section
, so they don't belong here. portal_skins
uses underscore and plural, as does modules. ERP and Open Source
use wrong case and are unrelated to the document. We can always add generic search
engine optimization tags to a document when rendering but - as keywords are not relevant for
search engine optimization currently, we should use them to properly structure content on ERP5. Altogether,
this is too many keywords for a document. Use keywords in a smart way and start
out with a list of keywords from a related document
#Document Theme Is Set Using Follow Up Software Product¶
Previously documents also had to be labelled with a solution to associate
the document with a software. Solutions have been moved to products and are
accessible via the Follow-Up¶ property. It is still mandatory to declare a
follow-Up category for all documentation content. Available software products:
- ERP5 Software (PD-ERP5)
- NayuOS Software PD-NayuOS
- JIO Software PD-JIO
- Wendelin Software PD-Wendelin
- CribJS Software PD-CribJS
- SlapOS Software PD-SlapOS
- RenderJS Software PD-RenderJS
- Re6st Software PD-Re6st
- OfficeJS Software PD-OfficeJS
- NEO Software PD-NEO
All documentation documents must have a software product defined.
#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
#Documentation Document Is Classified Using Publication Section¶
The publication section is used to sort and categorize documents. Without publication
sections defined, documents will not show up in predicate lists, indices or related documents
and are hard and maintain.
Note that without setting a group on a document you may not be able to change a documents workflow state (can't publish for example)
All documents must have publication section declared if it fits into
an one of the following:
-
All documentation documents must have one of the following defined:
- HowTo
- Guidelines
- Tutorial
- Design Document
- FAQ
- Technical Note
-
Documentation should also include at least one of the following:
- Documentation/User
- Documentation/Developer
#Documentation Document Must Have Meta Description¶
Borrowing from reasearch the description or abstract is a short summary of the
entire article. It allows the reader to determine whether the article is worth
reading. Write WHAT the article contains.
- Also used as description for search engine optimization
- Note 155 characters is the search engine limits for displaying text. Try to meaningful in the beginning.
- Must not contain double quotes (will not be parsed by search engines)
- Must not contain HTML5 elements (such as links)
Good example:
ERP5 Documentation HowTo showing how to use ZLDIF methods to publish data
to a LDAP database.
This is useful information because even though a reader might not know
what ZLDIF is, the description tells him it shows how to publish data to a
LDAP database.
Bad example:
This article explains how to use ZDLIF methods.
Useless you have expert knowledge which we should not expect from 99% of
documentation users.
#Documentation Document Must Have Introduction Paragraph¶
All documents must have a short introduction explaining in a few sentences
how the document can be used. Readers should see from this introduction whether to
continue reading or not. Note:The introduction does not have a headline
tag. Borrowing from research, the introduction leads the reader into the subject
and gives the reasons why the article at hand was written. Think of why
an article was written.
Good Examples:
A common problem is assessing whether ERP5 is a suitable solution. This page will
help you to determine if this is the case. It will introduce ERP5 along with
evaluation criteria as well as highlighting key factors that can make an ERP5
implementation a success or failure.
Bad Examples:
<h1>Introduction</h1>
<p>This HowTo teaches you how to write content.</p>
The bad example uses a headline and the description is not giving any information
on what is really contained in the document. Summarize the key content the user
can find here. Don't repeat the title or meta description, this is useless.
#Embedded SVG Image Must Have A Format Specified¶
SVG linking to external images without specifying their format is not allowed
for the same reason images in general must have a format specified.
Good Examples:
http://www.erp5.org/user-Reference.Of.My.Screenshot?format=png
Bad Examples:
http://www.erp5.org/user-Reference.Of.My.Screenshot?format=
#Headers Start At Level 1 And Are Not Numbered¶
Headlines (<h1,2,3,4,5,6>) should always start with the highest order (<h1>)
and structure a document. It is forbidden to skip levels.
Bad Examples:
<h1>Main Topic</h1>
<h3>Sub Topic</h3>
Good Examples:
<h1>Main Topic</h1>
<h2>Sub Topic</h2>
It is also forbidden to declare any attributes on the header tags.
Bad Examples:
<h1 id="foo" data-noise="loud" >Main Topic</h1>
Good Examples:
<h1>Main Topic</h1>
Also note that headers should not be manually numbered. Both the numbering
of the headers in the document and a generated table of content can be done
automatically via CSS stylesheets. This way adding content does not require
changing subsequent manual numbering.
Bad Examples:
<h1>Introduction</h1>
<p>This HowTo teaches you how to write content.</p>
The example uses a headline and the description is not giving any information
on what is really contained in the document. Summarize the key content the user
can find here. Don't repeat the title or meta description.
#Image Format Must Be SVG Or PNG¶
Images¶ in ERP5 should only be PNG or SVG images.
#Image Must Have Alt Attribute¶
Images must have an alt Attribute. Until retrieved automatic from image meta information, set this by hand.
The alt attribute should describe the content of the image and is being used in captions on report.
Good Examples:
< src="" alt="Screenshot how to debug ERP5 portal activities" />
Bad Examples:
<img src="" alt="Screenshot" />
#Image Must Have Alt Attribute¶ For Automatic Captioning
To add formatted captions to images, the image alt attribute
will be used.
Good Example:
<img alt="Title of this image" src=".." />
Bad Example:
<img src=".." />
<img alt="" src=".." />
#Image Must Have Format And Display Parameter In Url¶
Always set format display when working with images in document content
and provide a value to force ERP5 to render images in computation heavey formats and
sizes.
Good Examples:
< img src="NXD-Screenshot.Login.Screen?format=png∓display=thumbnail" />
Bad Examples:
< img src="NXD-Screenshot.Login.Screen" />
< img src="NXD-Screenshot.Login.Screen?format=" />
#Image Should Not Be Wrapped By Hand For Fullsize Viewing¶
When writing content, simply add a plain <img... />
tag with
proper link, abd alt attribute. Image tags will be
parsed and wrapped in links leading to a new tab with full screen display of
the respective image automatic (soon). Captions will also be added automatically
depending where the image is displayed.
#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
#Inline CSS And JavaScript Are Not Allowed¶
Document content represents text, no styling information (CSS) or
processing (JavaScript) should be included. These are meant for displaying
the content and will be added by whatever is used to display this page. Do not
complicate the work of the page renderer by adding CSS and JS directly in the
page.
Good Examples:
<h1>This is a title</h1>
Bad Examples:
<h1 style="font-weight:bold" class="main-header">This is a title</h1>
#Link Explaining Abbreviation Is Wrapped in Square Bracket And Uses Abbreviation As Link Text¶
Abbreviations must follow a certain format to have an automatic table of all
abbrevaitons built on rendering. The format for abbreviations is:
Good Example:
... enterprise resource planning [<a href="https://en.wikipedia.org/wiki/Enterprise_resource_planning" title="Enterprise Resource Planning|Description">ERP<a>]
#Link Text On Applicable And Referenced Documents Is AD/RD¶
The format for
referenced documents is:
[<a href="absolute/relative link" title="Title|Reference;Document Number/Issue">RD</a>]
Example:
.this is a link to Google [<a href="http://www.google.com" title="Google|Search Engine">RD</a>]
The format for applicable documents is:
[<a href="absolute/relative link" title="Title|Reference;Document Number/Issue">AD</a>]
Example:
... this applicable document [<a href="some_path_to_doc.pdf" title="Document Title|Description">AD</a>]
#Link To Applicable Or Referenced Document Uses Title And Is Wrapped In Square Brackets¶
Referenced documents and applicable documents are often used in multiple types
of documents.
- All referended/applicable documents will be parsed and numbered automatically
- A table of referenced document will be built and added to the web page
- The title tag is mandatory
- All other tags are optional
The format for referenced documents is:
[<a href="absolute/relative link" title="Title|Reference;Document Number/Issue">RD</a>]
Good Example:
.this is a link to Google [<a href="http://www.google.com" title="Google|Search Engine">RD</a>]
The format for applicable documents is:
[<a href="absolute/relative link" title="Title|Reference;Document Number/Issue">AD</a>]
Good Example:
... this applicable document [<a href="some_path_to_doc.pdf" title="Document Title|Description">AD</a>]
#PNG Is Saved In Image And SVG In Web Page Module¶
All PNG images in ERP5 belong into the image module. SVG Images are web illustrations and
therefore have to be kept in the Web Page Module.
#Sentence Starts With Capital Letter And Finishes With Semi-Colon Or Full-Stop¶
Sentences should be syntactically correct and natural as English. Every sentence
should be terminated with a period, a colon, or a semi-colon, according to the
context. Every sentence should be plain simple, and follow sentence case: only
first word is capitalized.
If you are not sure whether a noun should be singular or plural, use plural.
Good Example:
%d objects have been saved.
Bad Example:
%d object(s) has/have been saved.
The user does not care about whether 1 object has been saved. or 1 object have
been saved. as long as the user must choose which is appropriate by her own eyes.
It is more important to produce readable text.
If a sentence contains an URL or a path, you should insert space between the
URL or the path, so that the user can easily select it by a mouse.
Good Example:
The document is saved in /path/to/the/file .
Bad Example:
The document is saved in /path/to/the/file.
#Short Title¶ On Documentation Documents Uses Title Without Publication Section¶
The short title will be used in breadcrumbs and listbox titles as well as
related topic articles. It should have local context but still be meaningful by
itself. It will be used throughout the documentation for generating automatic lists
of relevant documentation so the field is mandatory and should be set to the title
put without the leading software and publication section.
Good Examples:
Title¶ => How To Request A Webrunner with Vifib
Short => Request Webrunner with Vifib
Bad Examples:
Title¶ => How to Debug ERP5 portal activities
Short =>
Short => How to Debug ERP5 portal activities
#SVG Image Must Have Format Specified In Url¶
SVG images (or images in general) should not be included on a web page without
the format being defined. Else the image will be loaded as-is which might mean
a format not possible to display by certain browsers.
Good Example:
http://www.erp5.org/user-Reference.Of.My.SVG?format=svg
Bad Example:
http://www.erp5.org/user-Reference.Of.My.SVG?format=
#Table Has Caption Defined After Tbody Tag¶
To add formatted captions to tables and add them to the overview of tables in a document,
the table caption element will be used. Note that the caption element
must be at the bottom of the table to be presented correctly.
Good Example:
<table>
<thead>
<tbody>
<tr>
<td></td>
</tr>
</tbody>
</thead>
<caption>This is an empty table</caption>
</table>
Bad Example:
<table>
<caption>THIS CAPTION IS AT THE WRONG POSITION</caption>
<thead>
<tbody>
<tr>
<td></td>
</tr>
</tbody>
</thead>
</table>
Captions will automatically be numbered and added to the overview of figures (images)
and tables of a text document.
#Table Uses Thead Tbody And Caption Tags¶
When creating tables please make sure you:
- tables use a <thead> for declaring headers
- <th> header cells will only be in the header
- a table <caption> is added after the <tbody>l; tag (necessary)
#Text From The User Interface Is Written In Italic¶
When referencing text the user should interact with, like clicking on the
"Create New Document" button, this text should be written in italic, not
in bold.
Good Examples:
Click the <i>New</i> button to continue
Bad Examples:
Click the <strong>New</strong> button to continue
#Use Only Allowed Html Tags¶
To keep things simple the list of HTML tags allowed in a document is limited.
No list variations (<dt>, <ol>), no "new" tags (<article>, <nav>).
The following tags can be used:
- <h1,2,3,4,5>
- <p>
- <span>
- <img>
- <b>
- <i>
- <em>
- <code>
- <pre>
- <ul>
- <li>
- <a>
- <section>
- <table, thead, tbody, tfoot, tr, th, td, caption>
#Use Path Links For Linking To Images Or Assets¶
We can distinguish between absolute, path and relative links.
Absolute Links¶
Pros:
- increase number of entries in cache, bloats cache
- beneficial for search engine optimization
- allows for dedicated zope "threading" of resources by domain
Cons:
- incompatible with restricted site access
- reduces portability from one website to another
Path Links¶
Pros:
- minimizes number of entries in cache
- compatible with restricted access on one site
- ensures content portability from one website to another
Cons:
- disadvantageous for zope "threading" resource utilization per domain
- inferior for search engine optimization
Relative Links¶
Pros:
- minimizes number of entries in cache
- compatible with restricted access on one site
- ensures content portability from one website to another
Cons:
- reduces ability to cache
- inferior for search engine optimization
- disadvantageous for zope "threading" resource utilization per domain
Because we favour security and portability, links to images and other HTML
assets should be path links (ex. /asset/NXD-Screenshort.Some.Thing?format=png),
except links to widely shared public assets (ex. fonts, standard icons) which
can also be absolute links to a Nexedi CDN for optimization purpose.
Good Example:
<a href="/asset/NXD-Screenshort.Some.Thing?format=png">Put titles on links</a>
Bad Examples:
<a href="http://www.erp5.com/documentation/devleper/NXD-Screenshort.Some.Thing?format=png">Put titles on links</a>
#A Large File Is Linked To Using Path Link¶
Because we favour security and portability, links to large BLOBS (video,
ISO images, etc.) should be path links (ex. /blob/NXD-Some.Big.File/Base_download
),
except links to widely shared public BLOBS (ex. NayuOS images) can also be
absolute links to Nexedi CDN for optimization purpose
Good Example:
<a href="/asset/NXD-Screenshort.Some.Thing?format=png">Put titles on links</a>
Bad Examples:
<a href="http://www.erp5.com/documentation/devleper/NXD-Screenshort.Some.Thing?format=png">Put titles on links</a>
Crime¶
#Document Content¶ Does Not Contain $Macros¶
It is not allowed to use macros (${this_is_a_macro}
) in web pages.
In case elements like a table of content needs to be added to a document,
please define this on the websection by declaring a renderer for this web section
and have the renderer load the default container and content layout and then
render the actual page differently.
Currently allowed exceptions include:
- Sale Offer/Sale Order generation - placeholders for dynamic table integration
The same applies to hrefs where by default no ${placeholder}
should
be used either.
Currently allowed exceptions include:
- Use of SubstitutionMappingDicts is discouraged, because this makes a
document viewable correctly only in the context of the respective web section
and potentially throws errors when a mapping dict is not accessible through
acquisition (most of dicts I found were located in the custom skin folder,
bad enough).
#Document Content¶ Should Never Contain Head Or Body Tag¶
The document content represents what would be inside the <body/>
tag of a webpage. The content will also always be loaded into a <body/>
of some renderer, so adding HTML, HEAD or BODY in the document content is not allowed.
The only exceptions allowed are for RenderJS gadgets.
#Embedded Image In SVG Must Be Reference Not Actual Image¶
Never embed external image/screenshot/illustration inside the SVG file. This
bloats up the file size and adds duplicate and impossible to maintain impages.
You should embed the links to these external image/screenshot/illustration.
#Never Use Relative Url As Embedded Reference Inside SVG¶
Don't put relative URL linking to external images inside an SVG. URLs should
always be absolute so the SVG remains portable and always points to the correct
location of the embedded image.
Good Examples:
http://www.erp5.org/user-Reference.Of.My.Screenshot?format=png
Bad Examples:
user-Reference.Of.My.Screenshot?format=png
#Url Should Never Contain ZODB Path¶
Document links should not be done using the zodb path. Reference¶s of documents should
always be used, IDs should never be used, even for intermediate documents.
Good Examples:
http://www.erp5.com/developer-ROTO
http://www.erp5.com/user-Front.Page.Screenshot?format=png
http://www.erp5.com/SOME_REFERENCE?format=svg
Bad Examples:
http://www.erp5.com/image_module/2732?format=svg
http://www.erp5.com/web_page_module/12234
http://www.erp5.com/web_page_module/SOME_ID
http://www.tiolive.com/nexedi/user-Front.Page.Screenshot?format=png
#SVG Images must not have a duplicate PNG Image¶
Never create duplicate png images of svg images. Use the svg images and
render them in the correct format using the format parameters!
Good Examples:
>img src="NXD-Image.Svg?format=png" alt="" /<
Bad Examples:
>img src="NXD-Image.Png.Copy.Of.Svg" alt="" /<
#To maintain a consistent way of creating content for the documentation and beyond, these guidelines contain rules for authors on how to create content. They cover both metadata (title, refrence description), HTML5 related instructions and information on the actual content being written.
Table of Contents
General Rules¶
- We write in English (UK), other languages depending on demand.
- Always use a spellchecker (like Language¶tool)
- All documentation documents will be created as Web Pages (or Test Pages).
- All documents are written in HTML5.
Type Of Documents¶
The documentation consists of different types of documents, which must be set in the publication section. The following types exist:
- Design Document, describing core components and architecture
- Guideline, setting conventions and patterns
- Tutorials, step-by-step instructions for beginners
- HowTos, small features explained in detail
- Technical Notes, short topics highlighted (leftover from erp5.org)
- FAQ, answer to a question asked, non-technical
Content in general should also have a publication section set whenever possible.
Document Meta Information¶
Meta information help identify, categorize and find a documents both for users and search engines. All documents must have the following:
Reference¶
Reference¶s should follow naming conventions. As there are multiple possibilities, we only use this one:
- Format: [ANCHOR]-[Publication Section].[Dotted.Name]-[VERSION]-[LANGUAGE].[TYPE]
- [ANCHOR] is the product, for example erp5 (all small caps), the company (ex. NXD) or the project (ex. P-ACME)
- [Publication Section] is one of FAQ, How-To, Guideline from above or any of the offical Websections
- publication section with multiple words are NOT separated and camel case (TechnicalNote)
- [Dotted.Name] is the title of the document with dots.
Note to Nexedians: These conventions also apply to internal documents outside of the documentation scope.
This way it is clear from the reference which software a document belongs to.
Example:
GOOD: erp5-HowTo.Create.Property.Sheet
GOOD: slapos-TechnicalNote.Create.Property.Sheet
GOOD: erp5-Tutorial.Create.Forum.Module
BAD: erp5-how-to-create-property-sheet
BAD: ERP5-HowTo.Create.Property.Sheet
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.
Short Title¶
The short title will be used in breadcrumbs and listbox titles as well as related topic articles. It should have local context but still be meaningful by itself. It will be used throughout for generating automatic content, so the field is mandatory for the documentation and when generating content pages.
Example:
GOOD: Title => How To Request A Webrunner with Vifib
Short => Request Webrunner with Vifib
BAD: Title => How to Debug ERP5 portal activities
Short =>
Note to Nexedians:: Extended guidelines for Nexedians on use of short title.
Title¶
- Will be used throughout the documentation for referencing
- Should work standalone and be self explanatory (vs the short title)
- Uppercase key words
- Format: [document title]
GOOD: How To Create Property Sheet
GOOD: Guideline on Authoring Content
BAD: Create Property Sheet
BAD: create property sheet
Description¶
Borrowing from reasearch the description or abstract is a short summary of the entire article. It allows the reader to determine whether the article is worth reading. Think of what the article contains.
- Also used as description for search engine optimization
- Note 155 characters is the search engine limits for displaying text. Try to meaningful in the beginning.
- Must not contain double quotes (will not be parsed by search engines)
- Must not contain HTML5 elements (such as links)
Good example:
ERP5 Documentation HowTo showing how to use ZLDIF methods to publish data
to a LDAP database.
This is useful information because even though a reader might not know what ZLDIF is, the description tells him it shows how to publish data to a LDAP database.
Bad example:
This article explains how to use ZDLIF methods.
Useless you have expert knowledge which we should not expect from 99% of documentation users.
Group¶
- Usually all documents should use Nexedi group
- Note that without explicitly setting a group you may not be able to change a documents workflow state (can't publish for example)
Classification¶
- Usually all documents should use Collaboration Team/Staffi
- Note that without explicitly setting a classification you may not be able to change a documents workflow state (can't publish for example)
Language¶
- For example: de, en, pt, fr
- Must respect the Naming Conventions¶.
Version¶
- For example: 001, 002, 003
- Must respect the Naming Conventions¶.
- When producing a new version of a document, always increase the version number.
Publication Section¶
The publication section is used to sort and categorize documents. Without publication sections defined, documentation will not show up in indices or related documents and are hard to find and keep track of.
- All documents must have publication section declared if it fits into an existing section.
- All documentation documents must have one of the following defined:
- HowTo
- Guidelines
- Tutorial
- Design Document
- FAQ
- Technical Note
- Documentation should also include at least one of the following:
- Documentation/User
- Documentation/Developer
Follow-Up¶
Previously documents also had to be labelled with a solution to associate the document with a software. Solutions have been moved to products and are accessible via the Follow-Up¶ property. It is still mandatory to declare a follow-Up category for all documentation content. Available software products:
- ERP5 Software (PD-ERP5)
- NayuOS Software PD-NayuOS
- JIO Software PD-JIO
- Wendelin Software PD-Wendelin
- CribJS Software PD-CribJS
- SlapOS Software PD-SlapOS
- RenderJS Software PD-RenderJS
- Re6st Software PD-Re6st
- OfficeJS Software PD-OfficeJS
- NEO Software PD-NEO
Also note the extended rules for Nexedians regarding other follow-up types.
Keywords¶
One of the most important fields to define are keywords, because they help showing related topics or searching for keyword related documents. Keywords allow us to structure the vast amount of documentation documents into useful groups.
- One keyword per line, no commas
- Names can be mixed case, like ERP5, MySQL, Senna
- All other keywords are lowercase
- All keywords are singular
- Seperate words by space, nothing else
- Publication sections are NOT keywords
Good examples
ERP5
search
portal catalog
MySQL
These are helpful keywords. ERP5 is defined to not mix with other software solutions, search will return this document for all users looking for information on searching in ERP5. portal catalog is written without underscore ("_") and MySQL as a name can be written in mixed case.
Bad examples
ERP5,
documentation,
HowTo,
portal_skins,
modules,
ERP,
Open Source
Commas will become part of the keywords, defining documentation will make all other documentation documents show up as related documents. HowTo is mixed case without space as separator and like documentation defined in publication_section
, so they don't belong here. portal_skins uses underscore and plural, as does modules. ERP and Open Source use wrong case and are unrelated to the document. We can always add generic search engine optimization tags to a document when rendering but - as keywords are not relevant for search engine optimization currently, we should use them to properly structure content on ERP5. Altogether, this is too many keywords for a document. Use keywords in a smart way and start out with a list of keywords from a related document
License¶
Every document should eventually have a licence, defining the scope to which a document can be used outside of the realm 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.
Related Documents¶
ERP5 provides an explicit (you declare manually) and implicit (done automatically) 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.
Applicable/Referenced Documents¶
Applicable/Referenced are only used in internal documents. Guideliens can be found in the extended rules for Nexedians
Document Content¶
Document content is written in HTML5 and is indepenent of the medium used. Documents should be viewable on the web, as a print out, exported as a book, pdf etc. This is why HTML5 is used (no Markdown or other shortcuts).
No Inline CSS and JavaScript¶
It also means, that external CSS style sheets and Javascript will handle the display of documents, so all documentation should be free of line style declarations and Javascript.
No ${Macros}¶
It is not allowed to use macros in web pages. In case elements like a table of content needs to be added to a document, please define this on the websection by declaring a renderer for this web section. General exceptions include:
- Sale Offer/Sale Order generation - placeholders for dynamic table integration
The same applies to hrefs, where by default no ${placeholder} should be used either. href exceptions include:
Introduction¶¶
All documents must have a short introduction explaining in a few sentences how the document can be used. Readers should see from this introduction whether to continue reading or not. Note:The introduction does not have a headline tag. Borrowing from research, the introduction leads the reader into the subject and gives the reasons why the article at hand was written. Think of why an article was written.
Good Example:
A common problem is assessing whether ERP5 is a suitable solution. This page will
help you to determine if this is the case. It will introduce ERP5 along with
evaluation criteria as well as highlighting key factors that can make an ERP5
implementation a success or failure.
Bad Example:
<h1>Introduction</h1>
<p>This HowTo teaches you how to write content.</p>
The example uses a headline and the description is not giving any information on what is really contained in the document. Summarize the key content the user can find here. Don't repeat the title or meta description.
Headlines¶
Headlines¶ (<h1,2,3,4,5,6>) should always start with the highest order (<h1>) and structure a document. It is forbidden to skip levels.
Bad Example:
<h1>Main Topic</h1>
<h3>Sub Topic</h3>
Good Example:
<h1>Main Topic</h1>
<h2>Sub Topic</h2>
It is also forbidden to declare any attributes on the header tags.
Bad Example:
<h1 id="foo" data-noise="loud" >Main Topic</h1>
Good Example:
<h1>Main Topic</h1>
Also note that headers should not be manually numbered. Both the numbering of the headers in the document and a generated table of content can be done automatically via CSS stylesheets. This way adding content does not require changing subsequent manual numbering.
HTML tags allowed¶
To keep things simply, the list of HTML tags allowed in a document is limited. No tables, no list variations (<dt>, <ol>), no "new" tags (<article>, <nav>). The following tags can be used:
- <h1,2,3,4,5>
- <p>
- <span>
- <img>
- <b>
- <i>
- <em>
- <code>
- <pre>
- <ul>
- <li>
- <a>
- <section>
- <table, thead, tbody, tfoot, tr, th, td, caption>
Code Sections¶
Code sections always use <pre><code>Your code</code></pre>
(there are many sections the other way around, please update if you find one). We are using HighlightJS, because it should detect languages automatically (else add a class="[language-miniscule]"
to the code tag) and was easy to extend to show line numbers and custom coloring. Currently we only added support for Python, CSS, HTML, XML, JavaScript, SQL and JSON. Please let me know if you want additional languages to be included. Also note that HTML markup must be escaped inside <code> blocks (use Textmechanic to quickly escape larger code blocks).
Tables¶
When creating tables please make sure you:
- have no parameters definded (cellspacing, borders...)
- tables use a <thead> for declaring headers
- <th> header cells will only be in the header
- rows are inside <tbody>
- all styling will be applied by CSS
- a table <caption> is added after the <tbody>l; tag (necessary)
Note, that <caption> is only necessary if a document should include an overview of all tables contained.
Highlighting Text¶
When referencing text the user should interact with, like clicking on the "Create New Document" button, this text should be written in italic.
Good Example:
Click the <i>New</i> button to continue
Bad Example:
Click the <strong>New</strong> button to continue
Hyperlinks¶
Links can be split into three different categories:
- absolute links:
http://www.erp5.com/press/NXD-logo?format=png
- path links:
/press/NXD-logo?format=png
- relative links:
./NXD-logo?format=png or NXD-logo?format=png
Absolute Links¶
Pros:
- increase number of entries in cache, bloats cache
- beneficial for search engine optimization
- allows for dedicated zope "threading" of resources by domain
Cons:
- incompatible with restricted site access
- reduces portability from one website to another
Path Links¶
Pros:
- minimizes number of entries in cache
- compatible with restricted access on one site
- ensures content portability from one website to another
Cons:
- disadvantageous for zope "threading" resource utilization per domain
- inferior for search engine optimization
Relative Links¶
Pros:
- minimizes number of entries in cache
- compatible with restricted access on one site
- ensures content portability from one website to another
Cons:
- reduces ability to cache
- inferior for search engine optimization
- disadvantageous for zope "threading" resource utilization per domain
Hyperlinks¶ Guidelines
The above definition leads to the following rules:
- Nexedi should have a common CDN (64 thread zope backend configured to serve ONLY anonymous content that can be HTTP cached)
- Besides utilizing:
cdn.nexedi.com (https)
- Every web site should have the following dedicated subdomains:
/asset
(16 thread zope)
/blob
(64 thread zope)
- Because we favour security and content portability, links from one HTML content to another HTML content should be relative link except link to content that only makes sense in a given context, for example an absolute lnk for a Nexedi press release which should be displayed on a Nexedi website.
- Because we favour security and portability, links to images and other HTML assets should be path links (ex. /asset/NXD-Screenshort.Some.Thing?format=png), except links to widely shared public assets (ex. fonts, standard icons) which can also be absolute links to a Nexedi CDN for optimization purpose.
- Because we favour security and portability, links to large BLOBS (video, ISO images, etc.) should be path links (ex.
/blob/NXD-Some.Big.File/Base_download
), except links to widely shared public BLOBS (ex. NayuOS images) can also be absolute links to Nexedi CDN for optimization purpose
No matter what link you use, they
- must use a target attribute
target="_blank"
if absolute
- must provide a meaningful title (search engine relevant)
- title format: [site name] | [site section] - [page title]
Images¶
Image Publication Section¶
If applicable, add one of the following publication sections:
- Design/Graphic/Flowchart
- Design/Graphic/Image
- Design/Graphic/Logo
- Design/Graphic/Screenshot
Image Reference¶
All images should follow a consistent naming scheme as the URL to an image is relevant for search engines and screen readers.
- CamelCase
- Dot Separator
- Format: [ANCHOR]-[Publication Section].[Title.With.Dots]
Example:
GOOD: NXD-Documentation.Guidelines.Content.Authoring.Screenshot
GOOD: erp5-graphic.official.logo.Image
BAD: documentation.graphic-authoring.Screenshot
Screenshot Format¶
To have a consistent format always use a FULL screenshot without bottom bar but without the url bar.
Bad Example:
This is a full browser screenshot. The bottom bar and everything above the url bar should be cropped.
Bad Example:
To ensure easy layouting on all print formats, the documentation should include no cropped to fit screenshots showing just snippets of code. Either use a <code> </code> for displaying code or supply a full browser screenshot.
Good Example:
Screenshot/Image Attributes¶
When writing content, simply add a plain <img... />
tag with proper link, attributes and following the rules outlined. Image tags will be parsed and wrapped in links leading to a new tab with full screen display of the respective image. Besides this an automatic image caption is created from the alt attribute.
Note that for generating a table of images within a sale order, offer or other module, the alt="" attribute is mandatory to be filled with just a description of the image.
GOOD: Screenshot how to debug ERP5
BAD: Screenshot
General Document Crimes¶
The following crimes are forbidden and go against using a DMS in a proper way.
Reference¶s
What should NOT be put as reference:
- No arbitrary numbers (not self explanatory):
- No abbreviations (not self explanatory):
Don't use zodb path in url¶
The document should not be linked using zodb path. Reference of document should always be used, IDs should never be used, even for intermediate documents.
Bad Examples:
- http://www.erp5.com/image_module/2732?format=svg
- http://www.erp5.com/web_page_module/12234
- http://www.erp5.com/web_page_module/SOME_ID
- http://www.tiolive.com/nexedi/12345/user-Front.Page.Screenshot?format=png
Good Examples:
- http://www.erp5.com/developer-ROTO
- http://www.erp5.com/user-Front.Page.Screenshot?format=png
- http://www.erp5.com/SOME_REFERENCE?format=svg
Images¶ Crimes
What is NOT acceptable:
- SVG containing inline screenshot/illustration.
- Screenshot/illustration (in png) shouldn't be put into the SVG file, but the SVG file has to contains links to external screenshot/illustration.
- SVG linking external images using relative URL. URL should be always absolute.
- user-Reference.Of.My.Screenshot?format=png is wrong
- http://www.erp5.org/user-Reference.Of.My.Screenshot?format=png is right.
- SVG linking external images without specifying format.
- http://www.erp5.org/user-Reference.Of.My.Screenshot?format= is wrong
- http://www.erp5.org/user-Reference.Of.My.Screenshot?format=png is right.
Web Pages Crimes¶
- Beware not to edit web page using FCK Editor, it will break your layout. Other editors are OK, but prefer raw text editor to write in HTML to have good looking code — it will help you a lot when you will have to update your page.
- Beware not include html, body, title, head tags on web page content
- Web page containing SVG image without specifying format is bad :
- Web page containing relative URL of SVG is bad :
${related_subject_list}