Recommandations pour la rédaction de la documentation AbulÉdu [La documentation d'AbulÉdu]

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
{{tag>version-8-08}}
====== 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 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.

<note warning>
N'introduisez pas de propos grossiers, insultants, diffamatoires, racistes, d'images pornographiques, violentes, etc. sans quoi vous seriez immédiatement radié des contributeurs.

N'oubliez pas de lire le [[http://wiki.ubuntu-fr.org/codedeconduite#code_de_conduite_ubuntu|Code de conduite Ubuntu]] si vous ne l'avez pas déjà fait !
</note>

===== Définitions dans le glossaire =====

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 [[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>
1.    Lien vers [[wpfr>Wikip%C3%A9dia|Wikipédia]]
2.    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.

Pour créer une nouvelle définition dans le glossaire, faites un lien vers le mot en question, comme dans les exemples ci-dessous :
<code>
1.    Lien vers la définition du [[glossaire:TX]]
2.    Lien vers le [[glossaire:glossaire]] en lui-même...
</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 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 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 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 =====

  * sur une capture globale, **mettez en avant la partie utile**. Exemples : 
    * 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-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».
  * **faites rentrer la capture dans la largeur de la page**, mais sans faire appel à la réduction de taille de dokuwiki (conserver la taille réelle si possible) : toujours dans l'exemple de l'outil réseau, j'ai volontairement [[abuledu:utilisateur:smbubuntu#methode_officielle|retouché le panneau Gnome]] en largeur pour qu'il rentre dans un écran de 800x600 pixels, sans avoir besoin de cliquer sur la capture pour la voir en taille réelle.
  * certaines captures ne sont là que pour pouvoir vérifier une commande tapée, il n'est donc pas nécessaire de respecter //tous// les critères précédents, mais simplement **qu'elles soient à portée de clic** si le lecteur en a besoin : typiquement dans la [[abuledu:utilisateur:smbubuntu#methode_alternative|connexion aux imprimantes partagées]], les captures sont réduites à côté du code (c'est lui qui est important), et les captures finales (les deux côte à côte) permettent de se faire une idée du résultat sans avoir besoin de les ouvrir : tant que la fenêtre n'est pas vide, c'est qu'on a réussi à faire ce qui était écrit, le nom des imprimantes et le serveur sur lequel elles sont connectées n'est pas nécessaire à la compréhension de la procédure.
  * si vous insérez plusieurs captures les unes à côté des autres ([[abuledu:administrateur:mise_a_jour#lancement_depuis_un_terminal_x|exemple]] et [[abuledu:utilisateur:smbubuntu#methode_alternative|un autre avec des applications différentes]]) **harmonisez les tailles** si vous le pouvez, c'est plus homogène.

===== Ouverture de nouvelle section =====


FIXME à compléter !

La première page d'une section porte son propre nom:
  * la première page de la section [[abuledu:abuledupro|AbulÉdu]] s'appelle «abuledupro»
  * idem pour les autres (developpeur:developpeur, etc)

===== Syntaxe Dokuwiki =====

==== 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://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.

 => pour commencer à préparer un article, ça se passe dans l'espace [[brouillons:brouillons]] :-)

==== Syntaxe spécifique à ce wiki ====

J'ai écrit [[http://wiki.splitbrain.org/plugin:note|le plugin de «Notes»]] car ce genre de visuel me paraît important dans une documentation. Je vous recommande de ne pas en abuser, les Notes ne sont là que pour souligner une idée importante, un tuyau qui peut faciliter la vie de l'administrateur/lecteur, ou encore un point critique à ne pas manquer sans quoi le déroulement serait stoppé.

Comment les utiliser : une phrase ou idée courte à l'intérieur d'un cadre ; on n'écrit pas un roman dans une note, sinon il vaut mieux créer carrément un nouveau paragraphe dans la page en cours, ou un article de wiki séparé.

<note tuyau>Exemple de tuyau qui vous facilite la vie : pour essayer GNU/Linux, installez une Ubuntu :-)</note>

Le code dokuwiki donne :

<code>
<note tuyau>
Exemple de tuyau qui vous facilite la vie : pour essayer GNU/Linux, installez une Ubuntu :-)
</note>
</code>

À la place du mot clé "**tuyau**", vous pouvez utiliser (par ordre d'importance et de couleur) : **classique**, **importante** ou **critique**, suivant l'importance du message que vous voulez faire passer.