Comment formater son article
Introduction
Cet article explique comment formater votre tutoriel. En suivant ce guide et celui sur le style de rédaction, votre tutoriel appliquera les recommandations d'ikoula.
Syntaxe wiki
Les tutoriaux ikoula doivent être formaté en utilisant la syntaxe wiki. Cet article va vous donner les exemples les plus courants de cette syntaxe. Vous trouverez plus de détails dans la section d'aide de mediawiki quant au formatage wiki.
Chapitres
Pour sectionner vos tutoriaux en chapitres, vous pouvez utiliser les niveaux de titre. Dès que vous placer un titre dans la page, tous les éléments suivants seront considérés comme faisant partie du nouveau chapitre, jusqu'au prochain titre de même niveau.
Cela peut être très utile pour améliorer la lisibilité de votre article en découpant les différentes étapes de réalisation.
Les différents niveaux de titre
Le titre de niveau 1 correspond au titre de l'article. Il est créé automatiquement lorsque vous créez votre page. Les autres titres se construisent en entourant votre titre par des signes "=". Le titre de niveau 2 correspond au premier titre de chapitre ou section.
Exemple pour le titre de cette section :
==Chapitres==
Plus vous mettrez de signe autour de votre titre, plus vous descendrez dans l'arborescence.
| Exemple | Résultat |
|---|---|
===Titre de niveau 3=== ====Titre de niveau 4==== =====Titre de niveau 5===== |
Titre de niveau 3Titre de niveau 4Titre de niveau 5 |
Il est à noter qu'une table des matière s'affiche automatiquement en tête d'article dès qu'il y a au moins 4 chapitres ou sous-chapitres.
Styles
Follow these conventions for when to use various element styles. Code styles are used in a variety of ways, so please see the earlier section for details about block and in-line code formatting.
You can format your text by using wiki markup. This consists of normal characters like asterisks, apostrophes or equal signs which have a special function in the wiki, sometimes depending on their position.
Gras
Voici comment mettre un terme en gras dans votre article.
| Exemple | Résultat |
|---|---|
'''texte en gras''' |
texte en gras |
Voici une liste d'éléments qui devraient être en gras.
- Texte visible d'une GUI
- Changement de contexte pour une commande, tel que changer d'utilisateur ou de serveur
- Noms d'hôte comme serveur-1
- Utilisateurs comme ikoula
- Prompts
- Liste de termes, comme :
- MySQL: moteur de base de données
- Apache: serveur web
- Eléments que le lecteur ne doit pas rater, sans trop en faire.
Italique
L'italique ne devrait être utilisé que pour introduire les termes techniques. Ex. : le serveur nginx sera utilisé comme reverse proxy.
| Exemple | Résultat |
|---|---|
''texte en italique'' |
texte en italique |
Notes et avertissements
L'utilisation de certaines balises HTML peut être nécessaire pour mettre en évidence certains éléments tels que des notes ou des avertissements.
| Exemple | Résultat |
|---|---|
<div style="background-color: #FFCC99;"> '''Note''': Ceci est une note.</div>
<div style="background-color: #FF9999;"> '''Warning''': Ceci est un avertissement.</div>
|
Note: Ceci est une note.
Warning: Ceci est un avertissement.
|
Blockquotes
Les blockquotes sont des blocs où votre texte est formaté différemment. Pour cela, il suffit de placer un espace en début de phrase, ou d'encadrer votre texte des balises <pre>. Votre texte sera alors formaté dans un cadre avec une police différente.
| Exemple | Résultat |
|---|---|
|
Texte important ''italique'' |
Texte important italique ou Texte important ''italique'' |
Comme vous pouvez le noter, l'utilisation de la balise <pre> fait que tout autre formatage à l'intérieur du bloc sera ignoré et considéré comme du texte à afficher. Si vous utilisez la première méthode, avec l'espace en début de ligne, sachez qu'un retour à la ligne fermera le cadre.
Nous préconisons d'utiliser la balise GeSHi ou la méthode des notes et avertissements pour afficher du code source ou des informations importantes.
Code source
Lorsque vous publiez un code source, vous devez appliquer la balise <syntaxhighlight>. Cela permettra à votre code de bénéficier d'une coloration syntaxique, le rendant plus lisible. Afin d'adapter la coloration au langage utilisé, ajoutez l'option lang="langage" dans la balise.
| Exemple | Résultat |
|---|---|
|
<syntaxhighlight lang="php"> |
<?
$hello = "Hello World";
echo $hello; // comment
?>
|
Vous trouverez sur le site de l'extension GeSHi la liste des langages supportés et quelques options supplémentaires, telle l'ajout de numéros de ligne ou la mise en évidence d'une ligne dans le code.
Référence à une application
Lorsque vous mentionnez une application, préférez utiliser la capitalisation du site officiel. Si le site web n'est pas consistent, choisissez une forme et essayez de l'être dans votre article.
Par contre, ne capitalisez pas les noms de paquets ou des commandes, si ces derniers ne le sont pas.
Exemple :
A MySQL database vs. the mysql command or the mysql-server package.
Listes
A chaque type de liste son utilisation.
Listes non-ordonnées
Ces listes sont utiles pour :
- les prérequis
- les checklists
| Exemple | Résultat |
|---|---|
* élément 1 * élément 2 |
|
Listes de définitions
Ces listes sont utiles pour :
- les termes et explications
- explications pour les variables dans une ligne de commande ou un fichier
| Exemple | Résultat |
|---|---|
;mot 1 : définition 1 ;mot 2 : définition 2-1 : définition 2-2 |
|
Listes ordonnées
Les listes ordonnées sont à utiliser avec parcimonie. Elles peuvent s'avérer pratiques pour lister l'ordre d'un processus, tel que le traitement d'une requête DNS.
| Exemple | Résultat |
|---|---|
# élément 1 # élément 2 |
|
Ces listes sont utiles pour :
- décrire un processus de traitement
Dans certains cas, l’utilisation d'un tableau sera préférable aux listes.
Tableaux
Voici un exemple simple de tableau. Cela peut être utile pour présenter plus facilement un code exemple et son résultat. Les tableaux sont structurés comme suit.
| {| | début de tableau |
| |+ | descriptif du contenu, optionnel; un seul par tableau positionné entre le début du tableau et la première ligne |
| |- | début de ligne, optionnel sur la première ligne -- le moteur de wiki prend en charge la première ligne |
| ! | cellule entête, optionnel. Les entêtes peuvent être mises soit sur la même ligne séparées par des doubles points d'exclamations (!!), soit sur des lignes séparées, chacune ayant son unique point d'exclamation (!). |
| | | cellule de donnée , requis! Les cellules de données consécutives d'un tableau peuvent être soit mises sur la même ligne séparées par une double barre verticale (||), soit sur des lignes séparées, chacune ayant son unique barre verticale (|). |
| |} | fin de tableau |
| Exemple | Résultat | ||||||
|---|---|---|---|---|---|---|---|
{|
|Orange
|Apple
|-
|Bread
|Pie
|-
|Butter
|Ice cream
|}
|
|
Pour plus d'information sur les tableaux, vous pouvez consulter le manuel wikimedia
Scripts et fichiers
N'oubliez pas de décrire le rôle des fichiers ou scripts que vous mentionnez. De cette manière le lecteur aura le même niveau d'information que vous et sera plus à même de comprendre votre démarche.
Scripts
Lorsque vous donnez le contenu d'un script ou d'un fichier de configuration, assurez vous qu'il soit commenté, de préférence au niveau des lignes concernées. Le but est que le lecteur comprenne l'ensemble des actions décrites, il est donc important d'être le plus didactique possible. De cette manière, il sera plus à même de personnaliser, mettre à jour ou diagnostiquer les problèmes de son serveur sur le long terme.
Si les fichiers que vous affichez possèdent des parties longues et/ou non intéressante pour votre tutoriel, vous pouvez omettre ces parties avec l’ellipse (...).
Nous vous recommandons l'utilisation de la balise GeSHi pour afficher le contenu des scripts ou fichiers. Cette dernière vous permettra, en plus de la coloration syntaxique, d'indiquer simplement des numéros de lignes et de surligner la ou les plus importantes. Nous vous recommandons d'utiliser le surlignage pour indiquer les lignes où il y a des modifications à effectuer.
| Exemple | Résultat |
|---|---|
<syntaxhighlight lang="apache" line start="10" highlight="5">
<VirtualHost *:80>
DocumentRoot /www/example1
ServerName www.example.com
# Other directives here
</VirtualHost>
</syntaxhighlight>
|
10<VirtualHost *:80>
11 DocumentRoot /www/example1
12 ServerName www.example.com
13
14 # Other directives here
15
16</VirtualHost>
|
Fichiers
Vous avez la possibilité d'insérer un fichier ou une image dans votre tutoriel. Le plus simple pour réaliser la chose est de mentionner le document dans votre article, puis de le mettre en ligne une fois la rédaction terminée. Si le fichier n'existe pas déjà, il sera pointé par un lien rouge. En cliquant sur ce lien, vous arriverez sur une page que vous permettra de téléverser votre fichier.
| Exemple | Résultat |
|---|---|
[[Media:mon_fichier.txt]] |
Il est à noter que le lien vers le fichier dépend exclusivement du nom du fichier. Nous vous recommandons d'utiliser des noms de fichiers aussi descriptifs que possible. N'oubliez pas d'inclure une description du fichier lorsque vous le mettez en ligne.
Images
Les images sont considérées comme des fichiers. Vous pouvez donc les inclure et les mettre en ligne de la même manière que les fichiers.
La seule différence avec un fichier est que l'image sera affichée dans le texte. Ce qui vous donne plus d'options pour son affichage.
La syntaxe a respecter est la suivante :
[[File:sample_image.jpg|options|description]]
Les options et la description sont facultatives.
| Exemple | Résultat |
|---|---|
[[File:sample_image.jpg|200px|thumb|right|modèle image]]
|
Vous trouverez plus d'informations concernant les différentes options possible sur la manipulation d'image sur le manuel de mediawiki.
Evitez d'utiliser des images trop lourdes et préférez utiliser les formats jpg, jpeg et png.
Touches du clavier
Pour décrire les touches de clavier, suivez ces recommandations :
- les écrire en MAJUSCULE
- utiliser la balise <span>
- utiliser le symbole + si elles doivent être pressées simultanément
| Exemple | Résultat |
|---|---|
Appuyer sur <span style="background-color: #E6E6E6;">CTRL</span>+<span style="background-color: #E6E6E6;">ALT</span>+<span style="background-color: #E6E6E6;">SUPP</span> puis '''Gestionnaire des tâches''' |
Appuyer sur CTRL+ALT+SUPP puis Gestionnaire des tâches |
Noms d'hôte
Nous vous recommandons d'utiliser des noms d'hôte les plus spécifique possible, qui soit en rapport avec le rôle du serveur.
Exemple :
- dns_serveur
- bdd_master
- proxy_nginx
- etc.
Noms de domaine
Lorsque vous traitez des noms de domaines, préférez utiliser le domaine domaine.tld comme domaine par défaut.
Si vous avez plusieurs noms de domaine à mentionner, vous pouvez choisir d'utiliser des noms tels que domaine-1.tld, domaine-2.tld, etc.
Pour les sous-domaines, nous vous recommandons d'utiliser un nom en rapport avec le rôle auquel ce sous-domaine sera rattaché, comme master.domaine.tld, slave.domaine.tld, bdd.domaine.tld, etc.
Adresses IP
Afin d'éviter de divulguer vos IP dans vos tutoriaux et d'être le plus clair possible, nous vous invitons à respecter les adresses réservées à la documentation. Dans notre cas, nous préférerons utiliser les adresses du bloc 203.0.113.0/24 pour tout ce qui est adresse publiques. Soit 203.0.113.0 à 203.0.113.255.
Pour les adresses des réseaux locaux et le localhost, vous pouvez conserver les IP que vous utilisez habituellement. C'est à dire :
- 10.0.0.0/8 - 10.0.0.0 – 10.255.255.255
- 172.16.0.0/12 - 172.16.0.0 – 172.31.255.255
- 192.168.0.0/16 - 192.168.0.0 – 192.168.255.255
- 127.0.0.0/8 - 127.0.0.0 – 127.255.255.255
Liens
fr:Créer un lien he:יצירת קישור ro:Creaţi un link ru:Создайте ссылку pl:Utwórz łącze ja:リンクを作成します。 ar:إنشاء ارتباط zh:创建链接 de:Erstellen einer Verknüpfung nl:Een koppeling maken it:Creare un link pt:Criar um link es:Crear un vínculo en:Create a link
Il existe deux types de liens :
- liens internes : qui pointe vers une page ou une section au sein des articles ikoula.wiki.
- liens externes : qui pointent vers un site tiers.
Liens internes
Les liens internes sont les liens qui pointent vers un autre article de Wikipédia. Les liens internes connexes à un article sont regroupés en fin d'article dans une sous-rubrique Articles connexes de la rubrique Voir aussi. Dans le cas où la rubrique Voir aussi ne présente pas de liens externes, on admet qu'elle soit utilisée pour les articles connexes.
[[Nom de l'article]]
|
Il est aussi possible de faire un lien interne à l'article (lien ancré) en utilisant un titre de section avec la syntaxe [[#Nom de la section]], ou vers une section d'un autre article de Wikipédia avec la syntaxe suivante :
[[Nom de l'article#Nom de la section]]
|
Pour faire apparaître un texte quelconque à la place du titre du lien, on peut utiliser la barre verticale (pipe) (|).
[[Wikipédia|texte à faire apparaître]]
|
texte à faire apparaître
|
Liens externes
Les liens externes sont des hyperliens qui mènent vers d'autres sites web que celui dans lequel se trouve la page. Dans les articles de ce site, on peut en trouver à deux endroits : dans la liste des références, et en fin d'article comme dans la rubrique « Voir aussi ».
| Exemple | Résultat |
|---|---|
[https://ikoula.wiki le wiki] |
|
http://ikoula.com |
|
[https://support.ikoula.com] |
GUIs
If your tutorial references a graphical user interface (GUI), you should include screenshots. You don't have to include a new screenshot for every single button, field, or link, but show enough that the reader can navigate the interface easily.
You can add arrows and outlines to the image to improve comprehension.
Please use bold text to refer to any element in the GUI, whether that is a button, link, checkbox, tab, popup text, or anything else.
Please specify the type of element you're referencing and its location on the page.
Example:
Select DNS from the left navigation menu. Then click anywhere in the IP address area (104.131.240.129 in the example) to edit the A record for the subdomain subdomain entry.
Click in the IP address area to edit the subdomain record
Press ENTER to save your change. The message Domain record was successfully updated will appear at the top of the screen.
For nested menus, it's fine to say something like:
From the top navigation menu, go to Settings > Networking > Domains.
Don't assume your reader is familiar with the GUI; that's why they're reading a tutorial about it.
Conclusion
Write a brief conclusion for your tutorial to summarize what has been accomplished, and what the reader might want to do next.
That's all! Check out the Style Guide, and happy writing!
Cet article vous a semblé utile ?
Activer l'actualisation automatique des commentaires