Contribution

Contribution guidelines

• Search first: 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.
• Contribute: The wiki is a resource for anyone to use. Just keep the content relevant, that is anything related to the project should be appropriate, as long as it meets our other guidelines.
• Explain: 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.
• Make improvements: If you find a typo or inaccurate information, just fix it.
• Keep it legal: Respect licenses and copyright. Only post content you own or provide attribution for content under a license that permits reuse. As always, our entire Terms of Service also apply to the wiki.
• Be nice: Keep the language clean (no swearing) and show respect for other contributors.
• Respect links: Provide redirects when you move content. Many people use the wiki and may have created bookmarks or linked to your content.
• Editing and Style: Review our specific style guidelines before contributing to the wiki.
• Write short edit:Do not make extensive page change at once. Best is to split your comment is many simple edits. Reverting changes will thus be easier.
• Preview your changes: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.

  Please avoid to write any text deeper than heading 4. Going below may lost the reader with too many sub-levels.

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

•  Blank horizontal lines are most of the time automatically managed by the wiki software formatting templates. Unless for a good reason, type your text, paragraph or headers, without manually added blank lines.
•  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 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.

Status

You may see sometimes some color blocks containing INCOMPLETE (yellow) or TO WRITE (red). These markers are Status

links

Internal links

You can create a link to a page/heading from the wiki, or any external web page. To do this, click the "Insert link" icon on the menu.

• Use the Search or Recently viewed menu to link to a wiki page.
• Use the Web Link menu to link a web page
• Use the Advanced menu to link and #Anchor or a Heading of a page. Example for a heading of a page
   Link : My Page Name#My Section

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.