Skip to content

Documentation Style

rzanoli edited this page Jun 10, 2014 · 19 revisions

EOP documentation is written as wiki pages by using the GitHub wiki editor. These are the adopted conventions to follow to create new wiki pages or edit existing ones:

  • Using English for the documentation.
  • Using proper page titles and avoid creating duplicate pages.
  • Annotate those parts which still need future work, clarification and/or explanation and/or verification with @TODO annotation marks.
  • Using relative links among wiki pages, e.g. [Documentation Style](Documentation Style)
  • Using relative paths for linking images, e.g. ../blob/gh-pages/wiki-images/step-by-step-tutorial/api_image2.jpg?raw=true
  • Markdown plain text formatting syntax should be used (http://en.wikipedia.org/wiki/Markdown).
  • Use the marker {version} when you want to refer to the release under development. During the release creation it will be substituted by the correct rlease number (e.g. 1.1.0).
  • Quite long pages should have an Abstract to introduce its content and an Index reporting links to the page's Sections. Following we report the template that should be used for the wiki pages:
An abstract is a brief summary of the page's content, and is used to help 
the reader quickly ascertain the page's purpose. Content contains an Index
reporting links to the page's Sections.

### Content:
1. [Section 1](#Section_1)
2. [Section 2](#Section_2)

## 1. <a name="Section_1"></a>Section 1
Here is the content of the Section 1 that can contain subsections too, e.g.
### Subsection
### Subsection

## 2. <a name="Section_2"></a>Section 2
Here is the content of the Section 2
Clone this wiki locally