...
- 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, alwaysspecify 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.
...
- Choose Insert > Markup
- Select Markdown
- Type or paste your text - the preview will show you how it will appear on your page
- 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.
...
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:
...
- 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.
| Note |
|---|
Do not make make an intensive use of external links. When possible, best is to include the text directly in the page. |
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.
...