Différences entre versions de « Comment rédiger un article pour la communauté iKoula »

De Ikoula Wiki
Jump to navigation Jump to search
(création de la page)
 
 
(20 versions intermédiaires par 2 utilisateurs non affichées)
Ligne 1 : Ligne 1 :
−
DigitalOcean is excited to continue building out its collection of technical articles. The goal of these articles is to provide well written, comprehensive pieces on a variety of topics related to server administration. To keep the DigitalOcean community unified and to ensure that articles fit the DigitalOcean writing style, we have developed the following writing guidelines.
+
<span data-link_translate_fr_title="Comment rédiger un article pour la communauté iKoula"  data-link_translate_fr_url="Comment rédiger un article pour la communauté iKoula"></span>[[:fr:Comment rédiger un article pour la communauté iKoula]][[fr:Comment rédiger un article pour la communauté iKoula]]
 +
<span data-link_translate_he_title="איך לכתוב מאמר הקהילה iKoula"  data-link_translate_he_url="%D7%90%D7%99%D7%9A+%D7%9C%D7%9B%D7%AA%D7%95%D7%91+%D7%9E%D7%90%D7%9E%D7%A8+%D7%94%D7%A7%D7%94%D7%99%D7%9C%D7%94+iKoula"></span>[[:he:איך לכתוב מאמר הקהילה iKoula]][[he:איך לכתוב מאמר הקהילה iKoula]]
 +
<span data-link_translate_ro_title="Cum să scrie un articol pentru comunitatea iKoula"  data-link_translate_ro_url="Cum+s%C4%83+scrie+un+articol+pentru+comunitatea+iKoula"></span>[[:ro:Cum să scrie un articol pentru comunitatea iKoula]][[ro:Cum să scrie un articol pentru comunitatea iKoula]]
 +
<span data-link_translate_ru_title="Как написать статью для сообщества iKoula"  data-link_translate_ru_url="%D0%9A%D0%B0%D0%BA+%D0%BD%D0%B0%D0%BF%D0%B8%D1%81%D0%B0%D1%82%D1%8C+%D1%81%D1%82%D0%B0%D1%82%D1%8C%D1%8E+%D0%B4%D0%BB%D1%8F+%D1%81%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D1%81%D1%82%D0%B2%D0%B0+iKoula"></span>[[:ru:Как написать статью для сообщества iKoula]][[ru:Как написать статью для сообщества iKoula]]
 +
<span data-link_translate_pl_title="Jak napisać artykuł do Wspólnoty iKoula"  data-link_translate_pl_url="Jak+napisa%C4%87+artyku%C5%82+do+Wsp%C3%B3lnoty+iKoula"></span>[[:pl:Jak napisać artykuł do Wspólnoty iKoula]][[pl:Jak napisać artykuł do Wspólnoty iKoula]]
 +
<span data-link_translate_ja_title="コミュニティ iKoula の記事を書く方法"  data-link_translate_ja_url="%E3%82%B3%E3%83%9F%E3%83%A5%E3%83%8B%E3%83%86%E3%82%A3+iKoula+%E3%81%AE%E8%A8%98%E4%BA%8B%E3%82%92%E6%9B%B8%E3%81%8F%E6%96%B9%E6%B3%95"></span>[[:ja:コミュニティ iKoula の記事を書く方法]][[ja:コミュニティ iKoula の記事を書く方法]]
 +
<span data-link_translate_ar_title="كيفية كتابة مقال عن عكلة المجتمع"  data-link_translate_ar_url="%D9%83%D9%8A%D9%81%D9%8A%D8%A9+%D9%83%D8%AA%D8%A7%D8%A8%D8%A9+%D9%85%D9%82%D8%A7%D9%84+%D8%B9%D9%86+%D8%B9%D9%83%D9%84%D8%A9+%D8%A7%D9%84%D9%85%D8%AC%D8%AA%D9%85%D8%B9"></span>[[:ar:كيفية كتابة مقال عن عكلة المجتمع]][[ar:كيفية كتابة مقال عن عكلة المجتمع]]
 +
<span data-link_translate_zh_title="如何写一篇文章为社区 iKoula"  data-link_translate_zh_url="%E5%A6%82%E4%BD%95%E5%86%99%E4%B8%80%E7%AF%87%E6%96%87%E7%AB%A0%E4%B8%BA%E7%A4%BE%E5%8C%BA+iKoula"></span>[[:zh:如何写一篇文章为社区 iKoula]][[zh:如何写一篇文章为社区 iKoula]]
 +
<span data-link_translate_de_title="Wie schreibe ich einen Artikel für die Gemeinschaft iKoula"  data-link_translate_de_url="Wie+schreibe+ich+einen+Artikel+f%C3%BCr+die+Gemeinschaft+iKoula"></span>[[:de:Wie schreibe ich einen Artikel für die Gemeinschaft iKoula]][[de:Wie schreibe ich einen Artikel für die Gemeinschaft iKoula]]
 +
<span data-link_translate_nl_title="Hoe schrijf een artikel voor de communautaire iKoula"  data-link_translate_nl_url="Hoe+schrijf+een+artikel+voor+de+communautaire+iKoula"></span>[[:nl:Hoe schrijf een artikel voor de communautaire iKoula]][[nl:Hoe schrijf een artikel voor de communautaire iKoula]]
 +
<span data-link_translate_it_title="Come scrivere un articolo per il iKoula di comunità"  data-link_translate_it_url="Come+scrivere+un+articolo+per+il+iKoula+di+comunit%C3%A0"></span>[[:it:Come scrivere un articolo per il iKoula di comunità]][[it:Come scrivere un articolo per il iKoula di comunità]]
 +
<span data-link_translate_pt_title="Como escrever um artigo para a Comunidade iKoula"  data-link_translate_pt_url="Como+escrever+um+artigo+para+a+Comunidade+iKoula"></span>[[:pt:Como escrever um artigo para a Comunidade iKoula]][[pt:Como escrever um artigo para a Comunidade iKoula]]
 +
<span data-link_translate_es_title="Cómo escribir un artículo para la comunidad iKoula"  data-link_translate_es_url="C%C3%B3mo+escribir+un+art%C3%ADculo+para+la+comunidad+iKoula"></span>[[:es:Cómo escribir un artículo para la comunidad iKoula]][[es:Cómo escribir un artículo para la comunidad iKoula]]
 +
<span data-link_translate_en_title="How to write an article for the community iKoula"  data-link_translate_en_url="How+to+write+an+article+for+the+community+iKoula"></span>[[:en:How to write an article for the community iKoula]][[en:How to write an article for the community iKoula]]
 +
{{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'{{Template:Hébergeur}}. Afin d'avoir une certaine unité de style d'écriture, nous avons décrit les recommandations suivantes.
  
−
Philosophy
 
−
DigitalOcean articles are written with the reader in mind! This is what distinguishes the DigitalOcean community from other knowledgebases. In practical terms, this means that an article’s author should:
 
  
−
Make no assumptions about the reader’s background knowledge of the subject
+
==Philosophie==
−
Explicitly spell out each step with as much clarity as humanly possible
+
Les articles de la base de connaissances sont écrits en pensant aux lecteurs ! Ce qui signifie que l'auteur d'un article doit :
−
Test their tutorials on a fresh server to ensure they work from scratch
+
* Ne pas faire de suppositions à propos du niveau technique du lecteur.
−
Write the tutorial to be understood by any smart user
+
* Décrire explicitement chaque étape le plus clairement possible.
−
Examples of some effective text that ensures the reader’s understanding are below:
+
* 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.
  
−
At this point you should have five files. If you're missing any, double-check the previous steps and re-download them:
 
  
−
ca.pem - StartSSL's Root certificate
+
==Structure==
−
private.key - The unencrypted version of your private key (be very careful no one else has access to this file!)
+
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.
−
sub.class1.server.ca.pem - The intermediate certificate for StartSSL
+
<br /><br />
−
ssl.key - The encrypted version of your private key (does not need to be copied to server)
+
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.
−
ssl.crt - Your new certificate
+
<br /><br />
−
from How To Set Up Apache with a Free Signed SSL Certificate on a VPS
+
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}} ont un but didactique et éducatif, apportant l'explication de chaque commande permettant au lecteur de comprendre les informations présentées.
 +
<br /><br />
 +
Ces explications jouent une part importante dans la compréhension, surtout s'il y a beaucoup d'informations à passer. Quand il y a beaucoup de modifications, telles que dans un fichier de configuration ou une longue installation, nous recommandons de détailler, autant que possible, chaque modification qui doit être faite.
 +
<br /><br />
 +
Deux choses doivent être évitées :
 +
* Les longs fichiers de configuration recommandés de copier sans explications.
 +
* Les scripts à télécharger et exécuter pour accélérer l'installation ou configurer le processus, sans que ces derniers ne soient explicitement détaillés.
  
−
another example is below:
+
En complément, si un article décrit une installation complexe, particulièrement quand cela concerne plusieurs {{Template:Serveur}}s, nous recommandons d'inclure une section détaillant le but du tutoriel.
−
 
+
<br />
−
We want to keep two ports open specifically. We want to keep our SSH port open (we're going to assume in this guide that this is the default 22. If you've changed this in your SSH configuration, modify your value here). We are also going to assume that this computer is running a web server on the default port 80. If this is not the case for you, you don't have to add that rule.
+
Si vous utilisez des diagrammes, n'oubliez pas d'inclure une légende, afin d'être compris de tous.
−
The two lines we're going to use to add these rules are:
+
<br />
−
 
+
<comments />
−
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
 
−
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
 
−
from How To Set Up a Firewall Using IPTables on Ubuntu 14.04
 
−
 
 
−
These two examples are effective because they provide the reader with all of the information they may need to complete the tutorial. Furthermore, the text above does not shy away from providing what may seem like additional information, where the authors determined it serves the needs of the reader.
 
−
 
 
−
Examples of ineffective text that may detract from the reader’s understanding can include sentences such as:
 
−
 
 
−
Edit the configuration file as needed
 
−
 
 
−
or
 
−
 
 
−
Open up your project’s directory
 
−
vim /path/to/project
 
−
 
 
−
Such text is ineffective because, while someone with a background in the topic may be able to use these instructions to complete the article, it does not span the spectrum of potential readers, who at this point may begin to encounter trouble following the instructions.
 
−
 
 
−
Structure
 
−
DigitalOcean articles are written to be as clear as possible and to have incredibly detailed steps. To ensure the reader is following the article closely and not missing any steps, DigitalOcean articles should be written with instructions alternating between explanations. In other words, as soon as a step should be taken, there should be an explanation of the command or step and then the step itself should be displayed.
 
−
 
 
−
You can see an example of this below:
 
−
 
 
−
Download the latest Serf package:
 
−
 
 
−
wget https://dl.bintray.com/mitchellh/serf/0.3.0_linux_amd64.zip
 
−
Install the unzip tool to unzip the package:
 
−
 
 
−
apt-get install unzip
 
−
Unzip the Serf package:
 
−
 
 
−
unzip 0.3.0_linux_amd64.zip
 
−
from How To Set Up a Serf Cluster on Several Ubuntu VPS
 
−
 
 
−
When trying to convey a lot of information, it may be tempting to combine commands on one line or just list multiple commands one after another without explanation. However, this is not the preferred method.
 
−
 
 
−
As readers go through each DigitalOcean article, especially those covering topics that they are not familiar with, there is an occasional temptation to just copy and paste the information presented, without a full understanding of what each command is executing. As DigitalOcean articles are focused on being educational, providing explanations of each command allows the reader to slow down and absorb all of the relevant information presented.
 
−
 
 
−
Additionally, this plays an important part in the way that larger amounts of information are conveyed. Where there are a lot of changes that need to be made consecutively, such as multiple to changes to a configuration file, or a long setup, we still recommend spelling out each change that needs to be made individually (if possible).
 
−
 
 
−
Two things that should be avoided are the following:
 
−
 
 
−
Long configuration files that are recommended for readers to paste in without explanation
 
−
Scripts that a reader should download and run to speed up the installation or set up process
 
−
Additionally, if an article is describing a complex set up process, especially one that may require multiple servers, we strongly recommend including a goal section in the tutorial. You can see an example of how the goal section should be structured.
 
−
 
 
−
DigitalOcean has a specific set up of usable icons. If you would like to include diagrams in your article, please indicate this in your correspondence with community editors so that we may include correctly set up diagrams.
 
−
 
 
−
Person
 
−
Because DigitalOcean tutorials are written as educational guides, as opposed to a blog or a forum post, we recommend maintaining a friendly but formal tone in the articles. One of the characteristics of the formal tone is avoiding the first person singular where possible in articles. Whereas in blogs, it is normal to involve yourself in the post, DigitalOcean tutorials should be limited to the first person plural and second person.
 
−
 
 
−
Some phrases to avoid include the following:
 
−
 
 
−
I’ve found…. I think…. I recommend….
 
−
However, while using the first person singular is discouraged, articles can be written effectively with the first person plural. A strong example of this in context can be seen below:
 
−
 
 
−
Now that we have an understanding of the basic components that are used in load balancing, let's get into the basic types of load balancing.
 
−
 
 
−
The person in the article should generally balance between first person plural (we, our, etc.) and second person (you, your, etc.)
 
−
 
 
−
Formality
 
−
DigitalOcean articles are written in a friendly but formal style. This means that articles do not include jargon, memes, or unnecessary humor. The focus of each tutorial is to provide the clearest explanation of a process possible. Conversely, where required, analogies can be a great way to elaborate on a topic or provide an additional angle to explain it.
 
−
 
 
−
You can see an excellent example of a strong, helpful analogy that works while still maintaining a formal, friendly style:
 
−
 
 
−
With fanout exchange, we can easily create a publish/subscribe pattern, working like an open to all newsletter. Producer, a newsletter broadcaster, sends periodic messages to the audience it may not even know (produces message and sends it to newsletter fanout exchange). New subscribers apply for the newsletter (binds own queue to the same newsletter fanout). From that moment the newsletter fanout exchange will deliver the message to all registered subscribers (queues).
 
−
 
 
−
from How To Use RabbitMQ and Python's Puka to Deliver Messages to Multiple Consumers
 
−
 
 
−
Images
 
−
Images provide a great way to quickly illustrate a point or provide additional clarification.
 
−
 
 
−
Images used in DigitalOcean tutorials should be no more than 745 pixels wide and should be hosted on Imgur.
 
−
 
 
−
Some examples of potential articles images may be highlighting GUI applications that were installed on a server and viewed in the browser, or to show a menu in the terminal that cannot be copied and pasted as text into the article. You can see an example of such an image here:
 
−
 
 
−
 
 
−
 
 
−
On the other hand, what is not recommended for images is screenshots of code or configuration files. Very often users would wish to copy and paste relevant information from a command or configuration file and would be rendered unable to do this with a screenshot of code.
 
−
 
 
−
An example of a non-recommended image would be the following:
 
−
 
 
−
 
 
−
 
 
−
Another helpful use for images is diagrams that illustrate more complex server setups. DigitalOcean diagrams use a set of custom icons that can be used to describe various situations. Let us know if you plan to include server diagrams in the article.
 
−
 
 
−
 
 
−
 
 
−
Topic/Focus
 
−
DigitalOcean articles are very self-contained. The goal of each article is that once a reader has completed it, they should have:
 
−
 
 
−
Set up something from start to finish
 
−
Installed something from start to finish
 
−
Thoroughly learned about a new topic
 
−
What this means for the writer is that the DigitalOcean article should either cover the topic thoroughly, or where prerequisites are needed, should link to another DigitalOcean article that covers the prior requirements.
 
−
 
 
−
If a background article does not exist in the DigitalOcean community, one should be written before a more advanced concept is introduced. This is imperative. However, this is often a great benefit to the author, as it provides a springboard for a full series that the author can set up with the exact information they need.
 
−
 
 
−
When writing a DigitalOcean article, we request that authors do not send readers offsite to gather information that could easily be added to the article.
 
−
 
 
−
For example, in an article about installing a glassfish server, the author shown below walked the reader through a simple Java installation, rather than linking to an offsite to a shorter tutorial that would cover it.
 
−
 
 
−
In order to get Oracle Installer of Java 7, we need to add a new apt repository. In order to use add-apt-repository, you need to install python-software-properties. Here's how to do it by apt-get:
 
−
 
 
−
sudo apt-get install python-software-properties
 
−
Now you can add the new repository and install from Oracle Installer:
 
−
 
 
−
sudo add-apt-repository ppa:webupd8team/java
 
−
Make source list up-to-date:
 
−
 
 
−
sudo apt-get update
 
−
Install Java 7 by apt-get:
 
−
 
 
−
sudo apt-get install oracle-java7-installer
 
−
After installing, confirm the current Java is Oracle version:
 
−
 
 
−
java -version
 
−
You will see this:
 
−
 
 
−
java version "1.7.0_51"
 
−
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
 
−
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)
 
−
from How To Install Glassfish 4.0 on Ubuntu 12.04.3
 
−
 
 
−
Another key aspect of DigitalOcean articles is that the reader should come away having set something up if the article discusses a setup. If, for example, the article discusses a PHP Framework, the author of the article should offer instructions on setting up a sample app before listing the details of actually using the framework. This serves two purposes:
 
−
 
 
−
The reader will be able to leave the tutorial with a sample environment that they can then build on.
 
−
The examples in the article are more concrete because each reader following the instructions will have the same set up. Offering a sample project ensures that all of the commands use actual working file paths which are easier to copy and paste and prevent user error issues when configuring.
 
−
Length
 
−
DigitalOcean articles do not require or dictate a specific length. However, we have generally found that in order to accomplish all they set out to do, DigitalOcean articles are usually between about 1500 and 5000 words each.
 

Version actuelle datée du 9 février 2017 à 13:00

fr:Comment rédiger un article pour la communauté iKoula he:איך לכתוב מאמר הקהילה iKoula ro:Cum să scrie un articol pentru comunitatea iKoula ru:Как написать статью для сообщества iKoula pl:Jak napisać artykuł do Wspólnoty iKoula ja:コミュニティ iKoula の記事を書く方法 ar:كيفية كتابة مقال عن عكلة المجتمع zh:如何写一篇文章为社区 iKoula de:Wie schreibe ich einen Artikel für die Gemeinschaft iKoula nl:Hoe schrijf een artikel voor de communautaire iKoula it:Come scrivere un articolo per il iKoula di comunità pt:Como escrever um artigo para a Comunidade iKoula es:Cómo escribir un artículo para la comunidad iKoula en:How to write an article for the community iKoula 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 ont un but didactique et éducatif, apportant l'explication de chaque commande permettant au lecteur de comprendre les informations présentées.

Ces explications jouent une part importante dans la compréhension, surtout s'il y a beaucoup d'informations à passer. Quand il y a beaucoup de modifications, telles que dans un fichier de configuration ou une longue installation, nous recommandons de détailler, autant que possible, chaque modification qui doit être faite.

Deux choses doivent être évitées :

  • Les longs fichiers de configuration recommandés de copier sans explications.
  • Les scripts à télécharger et exécuter pour accélérer l'installation ou configurer le processus, sans que ces derniers ne soient explicitement détaillés.

En complément, si un article décrit une installation complexe, particulièrement quand cela concerne plusieurs serveurs, nous recommandons d'inclure une section détaillant le but du tutoriel.
Si vous utilisez des diagrammes, n'oubliez pas d'inclure une légende, afin d'être compris de tous.


Vous n'êtes pas autorisé à publier de commentaire.

Récupérée de « https://fr-wiki.ikoula.com/index.php?title=Comment_rédiger_un_article_pour_la_communauté_iKoula&oldid=23948 »