Guidelines
Basic edition
-
-
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
If you are working with pictures
If an image is in your clipboard (screenshot), you can paste it in edit mode (see
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
[[hpc-admin:how_to_run_a_job]]
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.
-
TOC of the page
faq
in namespace
hpc
titled
FAQ
:
{{METATOC 1-5 >:hpc/faq|FAQ}}
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:
((my reference in a footnote))
Please don't put explanation in the footnote, only reference (
URL,msgid…) to avoid having to read back and forth.
You can see this
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
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.
-
Color notes
The 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
)
This is a simple note.
Add an important note
For tips
Add a warning note
<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>