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¶
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 Articles¶