Difference between revisions of "How to format article"
Line 1: | Line 1: | ||
− | |||
− | This article has been created by an automatic translation software. You can view the article source [[:fr:Comment formater son article|here]].<br /> | + | This article has been created by an automatic translation software. You can view the article source [[:fr:Comment formater son article|here]].<br /><span data-translate="fr"></span> |
Line 71: | Line 70: | ||
* Users like '''ikoula ''' | * Users like '''ikoula ''' | ||
* Quick | * Quick | ||
− | * List of terms as : | + | * List of terms, as : |
** '''MySQL ''': database engine | ** '''MySQL ''': database engine | ||
** '''Apache ''': webserver | ** '''Apache ''': webserver | ||
Line 344: | Line 343: | ||
<!--T:37--> | <!--T:37--> | ||
− | Vous avez la possibilité d'insérer un fichier or une image dans votre tutoriel. Le plus simple pour réaliser la chose est de mentionner le document dans votre article, | + | Vous avez la possibilité d'insérer un fichier or une image dans votre tutoriel. Le plus simple pour réaliser la chose est de mentionner le document dans votre article, Then 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. |
<br /> | <br /> | ||
Line 406: | Line 405: | ||
|- | |- | ||
| style="padding : 5PX ;"| | | style="padding : 5PX ;"| | ||
− | <nowiki >Support on <span style="background-color: #E6E6E6;">CTRL</span>+<span style="background-color: #E6E6E6;">ALT</span>+<span style="background-color: #E6E6E6;">SUPP</span> | + | <nowiki >Support on <span style="background-color: #E6E6E6;">CTRL</span>+<span style="background-color: #E6E6E6;">ALT</span>+<span style="background-color: #E6E6E6;">SUPP</span> Then '''Task Manager '''</nowiki> |
| style="padding : 5PX ;"| | | style="padding : 5PX ;"| | ||
− | Support on <span style="background-color: #E6E6E6;">CTRL</span>+<span style="background-color: #E6E6E6;">ALT</span>+<span style="background-color: #E6E6E6;">SUPP</span> | + | Support on <span style="background-color: #E6E6E6;">CTRL</span>+<span style="background-color: #E6E6E6;">ALT</span>+<span style="background-color: #E6E6E6;">SUPP</span> Then '''Task Manager ''' |
|} | |} | ||
<br /> | <br /> | ||
Line 420: | Line 419: | ||
* bdd_master | * bdd_master | ||
* proxy_nginx | * proxy_nginx | ||
− | * etc. | + | * etc. |
<br /> | <br /> | ||
Line 427: | Line 426: | ||
<!--T:48--> | <!--T:48--> | ||
When you are dealing with domain names, prefer to use the field '''domain.tld ''' as the default domain. | When you are dealing with domain names, prefer to use the field '''domain.tld ''' as the default domain. | ||
− | If you have multiple domain names to mention, you can choose to use names such as '''domain - 1.tld ''', '''domain - 2.tld '''etc. | + | If you have multiple domain names to mention, you can choose to use names such as '''domain - 1.tld ''', '''domain - 2.tld '''etc. | |
<br /><br /> | <br /><br /> | ||
− | For subdomains, we recommend that you use a name in connection with the role to which this subdomain will be attached, as '''master.domain.tld ''', '''slave.domain.tld ''', '''bdd.domain.tld '''etc. | + | For subdomains, we recommend that you use a name in connection with the role to which this subdomain will be attached, as '''master.domain.tld ''', '''slave.domain.tld ''', '''bdd.domain.tld '''etc. | |
<br /><br /> | <br /><br /> | ||
Line 455: | Line 454: | ||
Si vous souhaitez mettre des éléments de la capture en évidence, n'hésitez pas à y ajouter des flèches or cadres pour les pointer. Cela n'en rendra le tutoriel que plus compréhensif. | Si vous souhaitez mettre des éléments de la capture en évidence, n'hésitez pas à y ajouter des flèches or cadres pour les pointer. Cela n'en rendra le tutoriel que plus compréhensif. | ||
<br /><br /> | <br /><br /> | ||
− | Nous vous recommandons de mettre en gras les éléments que vous mentionnez et qui sont dans l'interface graphique, que ce soit un bouton, un lien, une case à cocheretc. | + | Nous vous recommandons de mettre en gras les éléments que vous mentionnez et qui sont dans l'interface graphique, que ce soit un bouton, un lien, une case à cocheretc. | |
<br /> | <br /> | ||
Don't forget to add a description when you turn the image online. | Don't forget to add a description when you turn the image online. | ||
Line 470: | Line 469: | ||
[[Category:Help]] | [[Category:Help]] | ||
− | + | <comments /> |
Revision as of 15:39, 23 September 2015
This article has been created by an automatic translation software. You can view the article source here.
This article describes how to format your tutorial. By following this guide and one on the writing style, your tutorial will apply the recommendations of ikoula.
Wiki syntax
Tutorials ikoula must be formatted using the wiki syntax. This article will give yor the most common examples of this syntax. Yor can find more details in the mediawiki help section as for the wiki formatting.
Chapters
To cut your tutorials into chapters, yor can use the levels of title. As soon as yor put a title in the page, all of the following items will be considered as part of the new chapter, until the next title of the same level.
This can be very useful to improve the readability of your article by cutting out the different stages of realization.
The different levels of title
The title of level 1 corresponds to the title of the article. It is created automatically when yor create your page. The tracks are built around your title by signs "=". The title of level 2 corresponds to the first title of chapter or section.
Example for the title of this section :
==Chapters ==
More you'll sign around your title, the more yor go down the tree.
Example | Result |
---|---|
===Level title 3=== ====Level title 4==== =====Level title 5===== |
Level title 3Level title 4Level title 5 |
It is worth noting that a table of contents automatically appears at the head of article as soon as there are at least 4 chapters or subchapters.
Styles
Yor can format your text using wiki syntax and a few HTML tags.
Bold
Here's how to end bold in your article.
Example | Result |
---|---|
'''bold text ''' |
bold text |
Here is a list of items that should be in bold.
- Visible text of a GUI
- Change of context for a control, such as changing user or server
- Hostnames as Server - 1
- Users like ikoula
- Quick
- List of terms, as :
- MySQL : database engine
- Apache : webserver
- Elements that the player should not miss, make it without too much.
Italic
Italics should only be used to introduce technical terms. E.g. : the nginx Server will be used as reverse proxy .
Example | Result |
---|---|
''italicized text '' |
italicized text |
Notes and warnings
The use of some HTML tags may be necessary to highlight certain elements such as notes or warnings.
Example | Result |
---|---|
<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
The blockquotes are blocks where your text is formatted differently. To do this, simply place a space at the beginning of sentence, or enclose your text from tags <pre>. Votre texte sera alors formaté dans un cadre avec une police différente.
Example | Result |
---|---|
Important text ''italic '' |
Important text italic or Texte important ''italic '' |
As you noted, the use of the tag <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'use the tag GeSHi or la méthode des notes et avertissements pour afficher du code source or 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.
Example | Result |
---|---|
<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 or 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 or des commandes, si ces derniers ne le sont pas.
Example :
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
Example | Result |
---|---|
* é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 or un fichier
Example | Result |
---|---|
;mot 1 : définition 1 ;mot 2 : définition 2-1 : définition 2-2 |
|
Listes ordonnées
The 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.
Example | Result |
---|---|
# é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. The 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. The 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! The 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 |
Example | Result | ||||||
---|---|---|---|---|---|---|---|
{| |Orange |Apple |- |Bread |Pie |- |Butter |Ice cream |} |
|
For more information on tables, please consult the Manual wikimedia
Scripts and files
N'oubliez pas de décrire le rôle des fichiers or 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 or 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 or diagnostiquer les problèmes de son serveur sur le long terme.
If the files that you post have long parts and /or non intéressantes pour votre tutoriel, vous pouvez omettre ces parties avec l’ellipse (...).
We recommend the use of the Balise GeSHi pour afficher le contenu des scripts or fichiers. Cette dernière vous permettra, en plus de la coloration syntaxique, d'indiquer simplement des numéros de lignes et de surligner la or les plus importantes. Nous vous recommandons d'utiliser le surlignage pour indiquer les lignes où il y a des modifications à effectuer.
Example | Result |
---|---|
<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 # Other directives here
14</VirtualHost>
|
File
Vous avez la possibilité d'insérer un fichier or une image dans votre tutoriel. Le plus simple pour réaliser la chose est de mentionner le document dans votre article, Then 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.
Example | Result |
---|---|
[[Media:mon_fichier.txt]] |
It is worth noting that the link to the file depends exclusively on the name of the file. It is recommended that you use names as descriptive as possible files. Don't forget to include a description of the file when you put it online.
Images
The 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.
The only difference with a file is that the image will be displayed in the text. What gives you more options to display.
The syntax to comply is :
[[File:sample_image.jpg|options|description]]
The options et la description sont facultatives.
Example | Result |
---|---|
[[File:sample_image.jpg|200px|thumb|right|modèle image]]
|
You can find more information about the different options available on the image manipulation on the mediawiki manual.
Avoid using too heavy images and prefer to use jpg, jpeg and png formats.
Keyboard keys
To describe the keyboard keys, follow these recommendations :
- write them in uppercase
- use the tag <span>
- utiliser le symbole + si elles doivent être pressées simultanément
Example | Result |
---|---|
Support on <span style="background-color: #E6E6E6;">CTRL</span>+<span style="background-color: #E6E6E6;">ALT</span>+<span style="background-color: #E6E6E6;">SUPP</span> Then '''Task Manager ''' |
Support on CTRL+ALT+SUPP Then Task Manager |
Host names
It is recommended that you use host names the most specific possible, that is in relation to the role of the server.
Example :
- dns_serveur
- bdd_master
- proxy_nginx
- etc.
Domain names
When you are dealing with domain names, prefer to use the field domain.tld as the default domain.
If you have multiple domain names to mention, you can choose to use names such as domain - 1.tld , domain - 2.tld etc. |
For subdomains, we recommend that you use a name in connection with the role to which this subdomain will be attached, as master.domain.tld , slave.domain.tld , bdd.domain.tld etc. |
IP addresses
To avoid to disclose your IP in your tutorials and be as clear as possible, we invite you to meet the reserved addresses to the documentation. In our case, we prefer to use the block addresses 203.0.113.0/24 for everything which is public address. Either 203.0.113.0 à 203.0.113.255.
For the addresses of local networks and localhost, you can keep the IP that you usually use. It means :
- 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
Links
Screenshots
If your tutorial describes actions to realize on a graphical interface, it is better to include screen shots to make it clearer.
Attention toutefois à ne pas en faire de trop. Il n'est pas question d'avoir une capture pour chaque bouton, zone de texte or lien, mais juste ce qu'il faut pour que le lecteur réussisse à vous suivre.
Si vous souhaitez mettre des éléments de la capture en évidence, n'hésitez pas à y ajouter des flèches or cadres pour les pointer. Cela n'en rendra le tutoriel que plus compréhensif.
Nous vous recommandons de mettre en gras les éléments que vous mentionnez et qui sont dans l'interface graphique, que ce soit un bouton, un lien, une case à cocheretc. |
Don't forget to add a description when you turn the image online.
Conclusion
Please include a short conclusion to your tutorial which will summarize what has been done and introduce what might be done subsequently.
You have everything you need to create your own articles ! In addition, you can also consult our article on the style iKoula, and good writing !
This article seemed you to be useful ?
Enable comment auto-refresher