====== Guidelines ====== 

==== Basic edition ====
  - Check the [[https://doc.eresearch.unige.ch/wiki/syntax|DokuWiki syntax]]  
  - You can try it out in the playground [[playground/playground]]
  - Remember that the Wiki is free to access by anyone
  - Remember to always sanitize :
    - your hands (because of covid-19), and
    - your data from any sensitive information (password, identities, etc.)
  - It is recommended to use the DokuWiki syntax. However, if you already have documentation in markdown and you cannot "translate" to DokuWiki syntax, then you can try to paste it between ''<markdown>''  and ''</markdown>'' elements. Please avoid using this as much as possible.
  - When something is incomplete or To Do, please use ''FIXME'' : <code>FIXME</code>

==== Pictures and other media ====
If you are working with pictures
  - If an image is in your clipboard (screenshot), you can paste it in edit mode (see [[https://www.dokuwiki.org/plugin:imgpaste|imgpaste plugin]] for more details.
  - If it's in a file, you have to upload it using the ''media manager''. Also make sure you are in the correct namespace.


==== Create a new page ====
    * Try to use underscore '_' as a seperator in pagenames.
    * Make sure you are creating the page in the correct namespace
    * For example : "How to run a job" in namespace hpc-admin:
      * in the URL bar ''baseURL/hpc-admin/how_to_run_a_job'', or
      * with the DokuWiki link syntax <code>[[hpc-admin:how_to_run_a_job]]</code>

==== Browse vs. search vs. TOC ====
  * You can find information with the search engine, but some people prefer to follow links or to read a table of content. So do all three !
  * Ideally, try to provide links to all the other pages from your namespace in the ''start'' page.
  * You can display the TOC of another page in any page. You can also create a page that will contain the TOC of multiple other pages. Just manually add a ''METATOC'' to all other pages you want to see.
      * For example: https://doc.eresearch.unige.ch/hpc/toc
      * TOC of the page ''faq'' in namespace ''hpc'' titled ''FAQ'' :<code>{{METATOC 1-5 >:hpc/faq|FAQ}}</code>

==== Synthesize and summarize ====
  * Try to **synthesize** and give the right amount of explanation
  * In case the procedure is too long, please use the following sub-sections :
    - **TL;DR** - short version, for example once we know how to use it
    - **Details** - detailed explanation, example, etc. when we need to understand how it works or how it all started.
  * All references (URL, Gitlab issues, msgid, etc.) should be marked as a footnote:<code>((my reference in a footnote))</code>
  * Please don't put explanation in the footnote, only reference (URL,msgid...) to avoid having to read back and forth.
  * You can see this [[hpc-admin:administration_maintenance_and_procedures#create_account | in this example]], where the TL;DR section contains links because they can be used during the procedure, but the all other references are footnotes.
  * If something needs basic knowledge of something "external" or a pre-requisite, please add a "Reference" section for example with links (i.e. : Salt stack documentation, How to use Linux for beginners, etc.).
  
==== Cleanup your outputs ====
  * Remove any extra spaces, typos or commands that are not required to understand what is going on (especially in console outputs).

==== code : scripts, console output and commands====
  * When you give some example of code (scripts, console output or commands), please use the right format
  * For source code, scripts or a list of command, use the ''code'' block and specify the language (if available), such as php, bash, etc.
  * If you refer to a script name or a path or a simple command, use two simple quotes so it stays inline.
  * For console outputs, please use the ''code'' block with language ''console''
    * N.B. : this is a simple CSS style that turns the text white and the background black.
    * <code><code console></code>


==== Color notes ====

The [[https://www.dokuwiki.org/plugin:note|plugin "Note"]] allows to add 4 types of color notes to draw attention or emphasize on some parts of your text : blue (no argument), yellow (''important''), red (''warning'') and green (''tip'')

<note>
This is a simple note.
</note>

<note important>
Add an important note
</note>

<note tip>
For tips
</note>

<note warning>
Add a warning note
</note>


<code>
<note>
This is my note ! Remember it!!
</note>

<note important>
Warning ! You're about to lose your mind ;-)
</note>

<note tip>
The clues are in the images.
</note>

<note warning>
Beware of the cat when you open the door !!
</note>
</code>