|
|
| Ligne 26 : |
Ligne 26 : |
| | <br /> | | <br /> |
| | Si vous utilisez des diagrammes, n'oubliez pas d'inclure une légende, afin d'être compris de tous. | | Si vous utilisez des diagrammes, n'oubliez pas d'inclure une légende, afin d'être compris de tous. |
| − |
| |
| − | ==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.
| |
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.
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 ceux qui nécessitent 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.