auteurs (basique)
Voici les points essentiels du guide pour la rédaction (ndt: et de traduction) des pages de documentation pour PmWiki.
[[MotWiki]]
lorsque vous avez besoin d'un lien.
PmWiki:NomDePage
ou Cookbook:NomDePage
pour établir des liens vers les pages qui ne font pas partie de la distribution.
[[!DocumentationToDo]]
. Placez la balise de catégorie près de la section où le travail doit être effectuer.
http://www.example.com/
comme préfixe pour les adresses URL d'exemple.
(:keywords:)
pour définir des mots-clés aidant lors des recherches.
!!
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.)
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.
(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é.
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.
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) |
lecteurs, auteurs (basique) |
Utilisez cette balise:
(:keywords mot, ...:)
Example for this page:
(:keywords Documentation, Guide, Aide:)
Ajoutez les mots-clés avant tout contenu visible de la page.
Toutes les pages du groupe PmWiki (ndt: ce qui ne semble pas ête le cas du groupe PmWikiFr) 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.
[[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.
Cookbook:NomDePage
et non [[Cookbook/NomDePage]]
.
[[MotWiki]]
. Tous les wiki n'ont pas les MotsWiki d'activés, ainsi lorsque vous rédigez une documentation, si un un MotWiki est supposée 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.
Une longue page de texte contigu peut décourager les lecteurs. Utilisez les titrage pour diviser votre page en plusieurs parties pertinentes. Les titrages permet aux lecteurs de rapidemment trouver l'information qu'ils cherchent.
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".
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.
''nomdefichier.ext'' ou ''local/config.php'' |
nomdefichier.ext ou local/config.php |
''cookbook/'' |
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.
Traduction de PmWiki.DocumentationGuidelines - Page originale sur PmWikiFr.DocumentationGuidelines
----
°
Page originale sur PmWikiFr.DocumentationGuidelines - liens arrières
Dernières modifications:
PmWikiFr.DocumentationGuidelines: 24 janvier 2006 à 02h41