How to write an article for the community iKoula
fr:Comment rédiger un article pour la communauté iKoula
This article has been created by an automatic translation software. You can view the article source here.
ikoula souhaite faire grandir sa base de connaissances techniques. Le but de ces articles est de fournir des tutoriels bien écrits, compréhensibles et sur une variété de sujets relatifs aux prestations fournies par l'hébergeur. Afin d'avoir une certaine unité de style d'écriture, nous avons décrit les recommandations suivantes.
Philosophie
Les articles de la base de connaissances sont écrits en pensant aux lecteurs ! Ce qui signifie que l'auteur d'un article doit :
- Ne pas faire de suppositions à propos du niveau technique du lecteur.
- Décrire explicitement chaque étape le plus clairement possible.
- Tester ses tutoriels, de préférence sur une installation fraîche, afin de s'assurer qu'ils fonctionnent "from scratch".
- Ecrire l'article pour être compris de tous.
Structure
Les articles sont écrits avec des étapes détaillées et pour être le plus clair possible. Pour être sûr que le lecteur suive l'article fidèlement et ne loupe pas une étape, les articles d'ikoula doivent être écrits en alternant les instructions et les explications. Autrement dit, à chaque étape il doit y avoir une explication de la commande ou de l'opération et cette dernière doit être affichée.
Quand on diffuse un certain nombre d'informations, il peut être tentant de combiner les commandes en une ligne ou de simplement les lister sans explication. Mais ce n'est pas la méthode privilégiée pour la compréhension des lecteurs.
Quand un lecteur parcourt un article, il est tentant de simplement copier/coller les informations présentées, sans compréhension de ce qu'il en est train de réaliser. Particulièrement si le sujet ne lui est pas familier. C'est pourquoi les articles de la base de connaissance d'ikoula have a purpose instructional and educational, providing the explanation for each allowing the reader to understand the information presented.
These explanations play an important part in the understanding, especially if there is much information to pass. When there are many modifications, such as a configuration file or a long installation, we recommend that detail, as much as possible, each change that must be made.
Two things must be avoided :
- Long configuration files featured copy without explanation.
- Scripts to download and run to accelerate the installation or configure the process, unless these are explicitly detailed.
In addition, if an article describes a complex installation, especially when referring to multiple servers, we recommend to include a section detailing the purpose of the tutorial.
If you use diagrams, don't forget to include a legend, in order to be understood by everyone.
Enable comment auto-refresher