Différences

Ci-dessous, les différences entre deux révisions de la page.

--- abuledu:developpeur:recommandations_de_redaction [2006/12/13 22:21]
jean
+++ abuledu:developpeur:recommandations_de_redaction [2016/01/21 12:00] (Version actuelle)
erics
@@ Ligne 1: / Ligne 1: @@
-<code>
+{{tag>version-8-08}}
-Documentation valable pour AbulÉdu Pro 1.4/1.6 et AbulÉdu PLM
-</code>
 ====== Recommandations pour la rédaction de la documentation AbulÉdu ======
 ===== Propos et idées =====
-Veillez à ce que vous écrivez soit bien en rapport avec le titre de l'article. Ne créez pas de hors-sujet ou de contresens. Au besoin n'hésitez pas à demander l'aide d'un relecteur sur [[web@abuledu.org|la liste de diffusion web]].
+Veillez à ce que vous écrivez soit bien en rapport avec le titre de l'article. Ne créez pas de hors-sujet ou de contresens. Au besoin n'hésitez pas à demander l'aide d'un relecteur sur le [[http://forum.abuledu.org|forum d'AbulÉdu]] et/ou [[web@abuledu.org|la liste de diffusion web]].
 Si vous sentez que vous faites un hors-sujet mais que l'idée vous paraît tout de même importante, créez une nouvelle page pour cette idée dans une section de la documentation ou dans le glossaire.
@@ Ligne 21: / Ligne 18: @@
 Avant de créer un article spécifique dans le glossaire, cherchez s'il y a une définition pertinente du mot sur [[http://fr.wikipedia.org/|Wikipédia]] et si oui, ne suffirait-elle pas ? En général, nous ne créons une page du glossaire que pour un terme de [[glossaire:jargon informatique]].
-Pour créer un lien vers Wikipédia (comme [[wp>Wikip%C3%A9dia|celui-ci]], regardez le code ci-dessous. Notez que pour un mot comportant des accents, il est nécessaire de réécrire le mot dans le lien (ligne 1), alors que pour un mot sans accent, le lien suffit (ligne 2) :
+Pour créer un lien vers Wikipédia (comme [[wpfr>Wikip%C3%A9dia|celui-ci]], regardez le code ci-dessous. Notez que pour un mot comportant des accents, il est nécessaire de réécrire le mot dans le lien (ligne 1), alors que pour un mot sans accent, le lien suffit (ligne 2) :
 <code>
-.    Lien vers [[wp>Wikip%C3%A9dia|Wikipédia]]
+.    Lien vers [[wpfr>Wikip%C3%A9dia|Wikipédia]]
-.    Lien vers le [[wp>Jargon]] sur Wikipédia.
+.    Lien vers le [[wpfr>Jargon]] sur Wikipédia.
 </code>
+Pour accéder à wikipédia en anglais, insérer : wp
+Pour accéder à wikipédia en français, insérer : wpfr
 Pour savoir qu'il faut écrire ''Wikip%C3%A9dia'', j'ai cherché «wikipédia» sur le site [[http://fr.wikipedia.org/|Wikipédia]], et j'ai copié-collé le dernier mot de la barre d'adresse de mon navigateur juste après ''wp>'' entre les doubles crochets. Je me suis permis de réécrire le mot proprement derrière le "''|''"((le caractère "pipe" |  s'obtient sur un clavier de PC en maintenant la touche "Alt Gr" pressée tout en pressant la touche 6 au-dessus du clavier)), pour qu'il soit affiché de manière lisible.
@@ Ligne 36: / Ligne 36: @@
 </code>
 Précédez le mot de ''glossaire:'' entre les crochets, comme ça le moteur saura que c'est un mot du glossaire et pas un article de documentation classique. En ligne 1, vous avez un lien vers la définition du [[glossaire:TX]], et en ligne 2 un lien vers la définition du [[glossaire:glossaire]] ; c'est tordu mais c'est pour montrer de quoi ça a l'air quand on pointe vers une définition qui n'existe pas encore en vue de la créer. Merci donc de ne pas créer [[glossaire:glossaire|cette page]] même si vous en avez les droits.
 ===== Rédaction de nouveaux articles =====
-  * **Écrivez un article sur un sujet que vous maîtrisez** depuis un bon moment, pas sur une fonctionnalité que vous avez découvert récement. Vous aurez ainsi eu le temps de faire le tour de la question, serez plus apte à trouver facilement une organisation didactique de l'information, à choisir des captures d'écran adaptées et utiles, et moins sujet à introduire des erreurs.
+  * **Écrivez un article sur un sujet que vous maitrisez** depuis un bon moment, pas sur une fonctionnalité que vous avez découvert récemment. Vous aurez ainsi eu le temps de faire le tour de la question, serez plus apte à trouver facilement une organisation didactique de l'information, à choisir des captures d'écran adaptées et utiles, et moins sujet à introduire des erreurs.
-  * **Un article ne doit pas être trop long** : cette apréciation est subjective, mais c'est important pour le poids des pages et leur interprétation sur les postes anciens, ainsi que pour la lisibilité générale de l'article et la facilité à trouver l'information : il faut pas avoir besoin de manier la roulette de la souris plus de quelques tours pour trouver l'information que l'on cherche dans une page. Il est par exemple innoportun d'écrire un article pour la configuration réseau de toutes les versions de Windows. On préfèrera un article :
+  * **Un article ne doit pas être trop long** : cette appréciation est subjective, mais c'est important pour le poids des pages et leur interprétation sur les postes anciens, ainsi que pour la lisibilité générale de l'article et la facilité à trouver l'information : il ne faut pas avoir besoin de manier la roulette de la souris plus de quelques tours pour trouver l'information que l'on cherche dans une page. Il est par exemple inopportun d'écrire un article pour la configuration réseau de toutes les versions de Windows. On préfèrera un article :
-    * **décrivant de manière générale** ou globale la configuration qui doit être faite. En quelques lignes, **les grands principes**((Comme ça un administrateur qui maîtrise son sujet aura l'information utile sans avoir à lire l'article détaillé pour la version spécifique qu'il utilise)),
+    * **décrivant de manière générale** ou globale la configuration qui doit être faite. En quelques lignes, **les grands principes**((comme ça un administrateur qui maitrise son sujet aura l'information utile sans avoir à lire l'article détaillé pour la version spécifique qu'il utilise)),
     * **indiquant** pour tel ou tel système **qu'il y a des spécificités** (sans les citer), incitant donc à lire l'article détaillé si le lecteur ne les connait pas,
     * et renvoyant vers tous les articles traitant chacun de la configuration détaillée (avec captures d'écran) d'une version donnée.
   * **Utilisez les titres et les sous-titres** : la table des matières est automatiquement générée à partir de ceux-ci, ils aident donc à se diriger dans un document lorsqu'on cherche une information très précise.
+  * **Utilisez les annotations suivantes** (Vérifier, Illustrer, Compléter, Actualiser) afin de permettre une recherche plus rapide des pages à modifier. Idéalement, ces annotations seront placées entre les balises %%<code> et </code>%%.
 ===== Captures d'écran =====
@@ Ligne 51: / Ligne 55: @@
     * regardez la [[abuledu:administrateur:premiers pas|capture de l'invite à webadmin]], elle met en avant deux points: la barre d'adresse, où l'on peut lire [[http://webadmin/]], l'adresse à taper pour arriver sur le bon site, et l'invite en elle-même, qui est l'endroit où l'administrateur débutant va devoir saisir son identifiant et son mot de passe. J'aurais pu capturer uniquement la fenêtre d'invite, mais la capture globale la replace dans son contexte.
     * sur la capture du lancement de l'outils d'administration du réseau, j'ai complètement effacé le bureau et les icones, et j'ai laissé apparaître l'info-bulle de la ligne du menu. Mon bureau est extrêmement personnalisé, un utilisateur novice n'aurait pas retrouvé un bureau "classique", j'ai donc préféré complètement l'effacer plutôt que simplement le rendre moins visible. L'information utile n'est pas polluée par un contexte trop différent.
-  * Dans le contexte d'une application donnée (typiquement [[abuledu:administrateur:configbaselinux#Ubuntu_Hoary|l'outils d'administration réseau]]), capturez **une vue complète** de l'application pour la première capture, **puis** seulement **les sous-fenêtres** ou sous-cadre utiles (le reste prend de la place sans apporter d'autre information que le contexte, qu'on connait déjà).
+  * Dans le contexte d'une application donnée (typiquement [[abuledu:administrateur:configbaselinux#Ubuntu_Hoary|l'outils d'administration réseau]]), capturez **une vue complète** de l'application pour la première capture, **puis** seulement **les sous-fenêtres** ou sous-cadres utiles (le reste prend de la place sans apporter d'autre information que le contexte, qu'on connait déjà).
   * si possible, **pré-sélectionnez** avec la souris **le champ ou le bouton que vous décrivez** dans le texte accompagnant la capture (dans notre exemple, il s'agit du champ de //l'interface internet eth0//) avant de faire la capture.
   * masquez, gommez ou **estompez vos modifications personnelles**. Même si elles sont esthétiques ou utiles, ça peut être déroutant dans une documentation pour un débutant qui s'attend à trouver de la doc sur le même système qu'il vient d'installer ou d'acheter. En revanche, laissez-les si vous écrivez un article sur «comment personnaliser telle ou telle chose».
@@ Ligne 71: / Ligne 75: @@
 ==== Généralités sur DokuWiki ====
-Je n'ai pas encore réalisé la traduction / adaptation de la syntaxe de DokuWiki. Cependant, Les contributeurs du site [[http://www.ubuntu-fr.org|Ubuntu-FR]] en ont [[http://wiki.ubuntu-fr.org/wiki/syntax|une qui est excellente]], je vous conseille donc de la lire en attendant. Avec ça vous pourrez commencer à écrire des articles.
+Je n'ai pas encore réalisé la traduction / adaptation de la syntaxe de DokuWiki. Cependant, Les contributeurs du site [[http://www.ubuntu-fr.org|Ubuntu-FR]] en ont [[http://doc.ubuntu-fr.org/wiki/syntaxe|une qui est excellente]], je vous conseille donc de la lire en attendant. Avec ça vous pourrez commencer à écrire des articles.
 Vous pouvez aussi «regarder le source d'une page((bouton en bas à gauche quand vous êtes visiteur))» ou «éditer une page((bouton en bas à gauche quand vous êtes identifié sur le site))» qui vous plait pour copier tout ou partie comme point de départ pour votre article.