Editing

Golden rules

• Before you start a new page, ask yourself if the content is necessary. Please browse already existing ones and see if the content you want to write can not be added in one of these pages.
• When editing, always specify what has been done and why. This can be done in the dedicated box What did you change. For those of you familiar with collaborative projects, see this action as a git commit.
• Do not make extensive page change at once. Best is to split your comment is many simple edits. Reverting changes will thus be easier.
• Before you save your work, it is a good idea to use the preview function. See what your changes look like.
  
  

Style

Writing style

•  Articles should be written using formal, professional, and concise language. Care should be taken to remove grammar and orthography errors through edit previews and proofreading.
•  Avoid contractions: "don't", "isn't", "you've", etc. should be "do not", "is not", and "you have", for example.
•  Avoid unnecessary shortening of word. In case of acronyms, when first use in a page, write the full name instead.
•  Avoids unnecessary capitalization", so use sentence case (like "Writing style" above) in page titles, section headings, table headings, and captions.

•  Talk directly to the reader: do not hesitate to use "you" or "we".

•  Do not use indefinite time references such as "currently", "at the time of writing" or "soon"; replace them with definite expressions such as "as of May 2016" etc.
•  Write objectively: do not include personal comments on articles. In general, do not write in first person.
•  When editing content, be consistent with the style used in the rest of the article.

Text formatting

Markup

You can type wiki markup directly into the editor, and Confluence will convert it as you type.

Example: _this is italic style

Markdown

Confluence supports inserting content in markdown.

To insert markdown in the editor:

1. Choose Insert > Markup
2. Select Markdown
3. Type or paste your text - the preview will show you how it will appear on your page
4. Choose Insert.

Highlighting

• Do not mix more than one highlighting method.
• The first relevant appearance of a term or name in an article can be highlighted  if regarded as worthy of particular attention.
• The preferable way of highlighting the name is using a link to a closely related article; if there are no possible pertinent links, bold can be used as a fallback solution.
• No formatting shall be applied to the anchor text of links.

Stressed/strong words or statements

• Use italic for words whose importance in giving the meaning to a sentence would not be recognized otherwise; usually they would be pronounced in a stressed way if reading out loud.
• When however particular attention is needed, words like "not", "only", "exactly", "strongly", "before"... can be highlighted in bold.
• The same goes for very important statements that cannot be put in a separate Warning or Note as they are an essential part of the section itself.

Quotations, references

For inline quotations, use "typewriter quotes". For block quotations, use indentation through a line-initial colon without any additional punctuation or formatting.

Acronym/abbreviation expansions

Use italic.

Section heading

• Headings should start from level 2, because level 1 is reserved for article titles.
• Do not skip levels when making subsections, so a subsection of a level 2 needs a level 3 heading and so on.
• Avoid using links in headings because they break style consistency and do not stand out well enough.

Code formatting

When inserting inline code, use monospace format. Example:

run the following command: $ this is the code to run

For large code block, insert the code block macro: choose your syntax, check the Collapsible option and use the Midnight theme.

"use strict";

// require npm packages
const bl = require('bl');
const https = require('https');

// require modules
const exportAsCsv = require('./exportAsCsv.js');
const address = require('./settings.js').address;

White space

•  Use a single space to separate sentences in the same paragraph (i.e. after period marks).
•  Avoid using multiple blank lines to space out paragraphs or sections.
•  Separate section headers from section bodies with an empty line.
•  Separate list characters from their items with a space.
•  Individual list items cannot be separated by blank lines, otherwise the wiki parser will start a new list for each item.
•  Separate special blocks (lists, code blocks, note, tip, warning etc.) from normal text with an empty line.

External links

On a page, use an external link the first time you introduce a term that need explanations or more details.This link can point to any article, Wikipedia entry or documentation which would be too long to insert in the page.

At the end of a page, in a See also section, you may list links of very special interest like official documentation or article of reference. Use a horizontal line by entering four minus symbol in a row, to separate the See also section title from the list of links.

Confluence software

The Daowiki is written with the help of Confluence, a team collaboration software. It is  developed and marketed by Atlassian. The software is considered as "one of the most popular wikis in corporate environments", easy to set up and use. Editing pages is fairly easy thanks to its powerful editor with many templates (called macro) and useful style editing functions. Its usage is very intuitive and do not ask knowledge of the wiki markup language, as it is the case with Mediawiki.

Please find on this page all the links to the needed resources to produce beautiful pages.