Voir la source de Comment rédiger un article pour la communauté iKoula

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.

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
Explicitly spell out each step with as much clarity as humanly possible
Test their tutorials on a fresh server to ensure they work from scratch
Write the tutorial to be understood by any smart user
Examples of some effective text that ensures the reader’s understanding are below:

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
private.key - The unencrypted version of your private key (be very careful no one else has access to this file!)
sub.class1.server.ca.pem - The intermediate certificate for StartSSL
ssl.key - The encrypted version of your private key (does not need to be copied to server)
ssl.crt - Your new certificate
from How To Set Up Apache with a Free Signed SSL Certificate on a VPS

another example is below:

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.
The two lines we're going to use to add these rules are:

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.