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 wants to grow its technical knowledge base. The purpose of these blogs is to provide tutorials well-written, comprehensible and on a variety of topics related to the services provided by the host. In order to have a certain unity of style of writing, we have described the following recommendations.
Philosophy
Knowledge base articles are written with readers in mind ! Which means that the author of an article should :
- Do not make assumptions about the technical level of the reader.
- Describe explicitly each step as clearly as possible.
- Test its tutorials, preferably on a fresh install, to make sure they work "from scratch ".
- Write the article to be understood by everyone.
Structure
The articles are written with detailed steps and to be as clear as possible. To be sure that the reader follow the article accurately and Magnifier not one-step, articles of ikoula must be written by alternating the instructions and explanations. In other words, at each stage there must be an explanation of the command or operation and it should be displayed.
When it broadcasts a number of information, it may be tempting to combine an online orders or simply list them without explanation. But this is not the preferred method for understanding of readers.
When a player scans an item, it is tempting to simply copy /Paste the information presented, without understanding of what it is to train. Especially if the subject is unfamiliar to him. This is why articles in the knowledge base of 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