Guide de documentation

auteurs (basique)

En résumé

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

  • Éviter les mots superflus.
  • 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écessitant une révision avec la balise [[!DocumentationToDo]]. Placez la balise de catégorie près de la section où le travail doit être effectué.
  • 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 structurer votre page en sections facilement modifiables. Mettez une majuscule en début de phrase sur vos titres.
  • Utilisez le plus possible un "style journalistique". Les faits d'abord. L'histoire plus tard. Pertinent/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 plupart d'explications supplémentaires, mais les éléments suivants fournissent plus de détails et donnent quelques indications sur "comment" informer.

KISS (Keep It Short & Simple)

En anglais KISS veut dire baiser mais c'est aussi l'acronyme de "Keep it Short & Simple" qui signifie "rester bref et simple" 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é.

Audiences et niveaux 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 à connaitre 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 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 types 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)

Mots-clés pour faciliter la recherche

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.

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

Toutes les pages du groupe PmWiki (ndt: ce qui ne semble pas être 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.

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

Titres de sections

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

Style journalistique

Lors d'une rédaction "journalistique", 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 personnelle. La plupart des auteurs sont réticents 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''

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/''

cookbook/

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

Page originale sur PmWikiFr.DocumentationGuidelines - Référencé par
Dernières modifications:
PmWikiFr.DocumentationGuidelines: 20/08/2009