Recommandations pour la rédaction de la documentation AbulÉdu

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 forum d'AbulÉdu et/ou 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.

Avant de créer un article spécifique dans le glossaire, cherchez s'il y a une définition pertinente du mot sur 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 informatique.

Pour créer un lien vers Wikipédia (comme 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) :

1.    Lien vers [[wpfr>Wikip%C3%A9dia|Wikipédia]]
2.    Lien vers le [[wpfr>Jargon]] sur Wikipédia.

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 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 “|”¹⁾, 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 :

1.    Lien vers la définition du [[glossaire:TX]]
2.    Lien vers le [[glossaire:glossaire]] en lui-même...

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 : Le Terminal léger ou «Terminal X», et en ligne 2 un lien vers la définition du 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 cette page même si vous en avez les droits.

• É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²⁾,
  • 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>.

• sur une capture globale, mettez en avant la partie utile. Exemples :
  • regardez la 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 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 retouché le panneau Gnome en largeur pour qu'il rentre dans un écran de 800×600 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 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 (exemple et un autre avec des applications différentes) harmonisez les tailles si vous le pouvez, c'est plus homogène.

à compléter !

La première page d'une section porte son propre nom:

• la première page de la section AbulÉdu s'appelle «abuledupro»
• idem pour les autres (developpeur:developpeur, etc)

Je n'ai pas encore réalisé la traduction / adaptation de la syntaxe de DokuWiki. Cependant, Les contributeurs du site Ubuntu-FR en ont 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³⁾» ou «éditer une page⁴⁾» 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

J'ai écrit 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é.

Exemple de tuyau qui vous facilite la vie : pour essayer GNU/Linux, installez une Ubuntu

Le code dokuwiki donne :

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

À 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.