From GraphingShakespeare

PmWikiFr: Guide de documentation

auteurs (basique)

En résumé

Voici les points essentiels du guide pour la rédaction (ndt: et de traduction) des pages de documentation pour PmWiki.

• Éviter les mots .
• Utiliser un balisage le plus simple possible pour la documentation. (KISS).
• Ne vous fiez pas aux liens MotsWiki; Utilisez [[MotWiki]] lorsque vous avez besoin d’un lien.
• Utiliser PmWiki:NomDePage ou Cookbook:NomDePage pour établir des liens vers les pages qui ne font pas partie de la distribution.
• Signalez les pages incomplètes ou nécissitant une révision avec la balise [[!DocumentationToDo]]. Placez la balise de catégorie près de la section où le travail doit être effectuer.
• Utilisez http://www.example.com/ comme préfixe pour les adresses URL d’exemple.
• Mettez tous les styles spécifique à la documentation dans PmWikiFr.GroupHeader.
• N’utilisez pas les balises de tableaux pour des choses autres que des tableaux.
• Utilisez la balise (:keywords:) pour définir des mots-clés aidant lors des recherches.
• Indiquez le public visé et le niveau de difficulté de votre documentation.
• Utilisez !! et !!! pour strucutrée votre page en section facilement maintenable. Mettez une majuscule en début de phrase sur vos titres. . ( ndt: la phrase originale est : “Use “sentence capitalization” for headings (i.e., capitalize only the first letter of the heading and any proper names)”, néanmoins ceci est une convention typographique typiquement anglo-saxonne.)
• Utilisez le plus possible un “style journalistique”. Les faits d’abord. L’histoire plus tard. Pertinant/percutant (voir plus loin).
• Ne signez pas votre documentation à moins qu’il s’agisse d’une opinion personnelle que vous ne souhaitez pas voir modifier.

En détail

Les points précédents ne nécessitent pas pour la pluspart d’explications supplémentaires, mais les éléments suivants fournissent plus de détails et donnent quelques indications sur “comment” informer.

KISS (Keep It Simple Stupid)

(ndt:en anglais KISS veut dire baiser mais c’est aussi l’acronyme de :”Keep it Simple, Stupid” qui signifie “rester simple et stupide” et dont le sens principal est d’éviter toute complexité inutile.) Gardez le balisage de la documentation le plus simple possible. La documentation de Pmwiki est elle-même une démonstration de ce qui peut être accompli et comme la plupart des documents collaboratifs, ceux-ci doivent rester accessibles au plus grand nombre d’auteurs. Il est important de garder un balisage lisible et pas uniquement le rendu affiché.

Comment définir pour quelle audience est destinée un document et son niveau de difficulté.

Ce classement par type d’audience n’est pas supposé être exclusif et obligé, il s’agit juste d’une convention pratique pour aider les utilisateurs à connaître ce qui est pertinent pour eux. Pour une description complète voir : Documentation des audiences.

• Les mots-clés définissant les audiences sont : lecteurs, auteurs, administrateurs (et tous regroupant les trois types)
• Les mots-clés définissant les définissant les niveaux de difficulté sont : basique, intermédiaire, avancé.

Il n’y a pas de relation directe entre un type d’audience et son niveau - l’audience classifie les différents type d’utilisation du wiki, alors que le niveau indique la difficulté relative du contenu.

Balise suggérée (à placer près ou tout en haut de la page):

%audience% lecteurs, auteurs (basique)

Comment fournir des mots-clés pour faciliter la recherche

Utilisez cette balise:

Example for this page:

Ajoutez les mots-clés avant tout contenu visible de la page.

Comment être sûr que tous les liens fonctionnent.

Toutes les pages du groupe PmWiki (ndt: ce qui ne semble pas ête le cas du groupe PmWiki Fr) ou du site pmwiki.org ne sont pas forcément livrées dans la distribution. Prenez garde à la création des liens des pages non distribuées.

• Utilisez soit la balise [[PmWiki:NomDePage]] ou soit la balise [[Cookbook:NomDePage]] pour créer des liens avec les pages ne faisant pas partie de la version distribuée de PmWiki.
• Les liens de la documentation vers un module du cookbook doivent être spéfiés tel que Cookbook:NomDePage et non [[Cookbook/NomDePage]].
• Ne vous fiez pas au lien de type MotsWiki, utilise la balise [[MotWiki]]. Tous les wiki n’ont pas les MotsWiki d’activés, ainsi lorsque vous rédigez une documentation, si un MotWiki est supposé faire référence vers une autre page alors entourez le de double crochets tel que : [[MotWiki]]. Toutes les occurences d’un MotWiki n’ont pas besoin d’être un lien, généralement la première suffit.

Utilisez des titrages pour chaque grande partie de l’information.

Une longue page de texte contigu peut décourager les lecteurs. Utilisez les titrages pour diviser votre page en plusieurs parties pertinentes. Les titrages permet aux lecteurs de rapidemment trouver l’information qu’ils cherchent.

Utilisez un style de rédaction journalistique lorsque c’est posssible.

Lors d’une rédaction “journalisitique”, vous racontez l’histoire entière d’abord, puis vous élaborez les détails ensuite. Ceci permet aux lecteurs d’avoir une idée rapide du sujet dans un premier temps - et pour la plupart, c’est suffisant. Quiconque désire aller plus loin dans la discussion ou cherche plus d’exemples lit alors la suite. Dans les journaux, l’intégralité du sujet est contenu dans le premier paragraphe. Les journaux utilisent des phrases courtes. Les phrases sont “percutantes”.

Ne “signez” pas la documentation

Il est très facile dans PmWiki de signer vos contributions en insérant la balise ~~~ dans la fenêtre d’édition. Une signature est appropriée lorsque vous posez une question ou vous exprimez une opinion personelle. La plupart des auteurs sont rétiçants pour éditer un contenu signé. Cependant, généralement la documentation n’est pas une opinion personnelle, et l’édition doit être encouragée. Les curieux peuvent utiliser l’historique pour voir qui a dit quoi.

Quelques styles typographiques suggérés

• pour indiquer un nom de fichier, utilisez la balise d’emphase.

''nomdefichier.ext'' ou ''local/config.php''

• pour indiquer un nom de répertoire seul, utilisez la balise d’emphase en y incluant à la fin un slash (/).

''cookbook/''

NOTE
Quelques unes des discussions à propos de ce guide sont conservées sur PmWiki:DocumentationGuidelines-Comments(en anglais). Par commodité tous les commentaires ultérieurs peuvent être fait ici PmWiki:DocumentationGuidelines-Comments.