Nexedi Extended Guidelines for Authoring and Content Creation

[out-of-date] Please use individual guidelines.
  • Last Update:2017-03-27
  • Version:003
  • Language:en

These guidelines provide extended rules and information for Nexedi internal documents beyond the standard documentation.

Table of Contents

Document Meta Information

Meta information help identify, categorize and find a documents both for users and search engines. All documents must have the following:

Short Title

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

Follow-Up

For internal documents the follow up also can be set in the following cases:

  • Sale Offer
  • Sale Order
  • Sale Opportunity
  • Project

Citations and References

Referenced/Applicable Document Links

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>]

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>]

Abbreviations

Abbreviations should also follow a certain format to have an automatic table of all abbrevaitons built on rendering. The format for Abbreviations is: 

... enterprise resource planning [<a href="https://en.wikipedia.org/wiki/Enterprise_resource_planning" title="Enterprise Resource Planning|Description">ERP<a>]

Table Of Content/Related Documents

It is possible to add an automatic table of content along with a list of related documents (based on keywords set on the current article) to a document. However this needs to be defined on the websection containing the respective web page. XXX HOW? .

Table/Image Captions

To add formatted captions to images and tables, the image alt attribute and 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.

Related Articles