Différences entre versions de « Comment rédiger un article pour la communauté iKoula »
(création de la page) |
(rédaction) |
||
| Ligne 1 : | Ligne 1 : | ||
| − | + | {{iKoula}} souhaite faire grandir sa base de connaissances technique. Le but de ces articles et de fournir des tutoriaux bien écrits, compréhensifs 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 tutoriaux, 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. | |
| − | + | <br /><br /> | |
| − | + | 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. | |
| − | + | <br /><br /> | |
| − | + | 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 /> | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | Structure | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
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). | 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). | ||
| Ligne 71 : | Ligne 28 : | ||
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. | 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 | + | ==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. | 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. | ||
| Ligne 83 : | Ligne 40 : | ||
The person in the article should generally balance between first person plural (we, our, etc.) and second person (you, your, etc.) | The person in the article should generally balance between first person plural (we, our, etc.) and second person (you, your, etc.) | ||
| − | Formality | + | ==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. | 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. | ||
| Ligne 92 : | Ligne 49 : | ||
from How To Use RabbitMQ and Python's Puka to Deliver Messages to Multiple Consumers | from How To Use RabbitMQ and Python's Puka to Deliver Messages to Multiple Consumers | ||
| − | Images | + | ==Images== |
Images provide a great way to quickly illustrate a point or provide additional clarification. | Images provide a great way to quickly illustrate a point or provide additional clarification. | ||
| Ligne 111 : | Ligne 68 : | ||
| − | Topic/Focus | + | ==Topic/Focus== |
DigitalOcean articles are very self-contained. The goal of each article is that once a reader has completed it, they should have: | DigitalOcean articles are very self-contained. The goal of each article is that once a reader has completed it, they should have: | ||
| Ligne 151 : | Ligne 108 : | ||
The reader will be able to leave the tutorial with a sample environment that they can then build on. | 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. | 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 | + | |
| + | ==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. | 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 du 2 juillet 2015 à 11:34
ikoula souhaite faire grandir sa base de connaissances technique. Le but de ces articles et de fournir des tutoriaux bien écrits, compréhensifs 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 tutoriaux, 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.
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.