From Actux Wiki

PmWikiFr: 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.

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.

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.

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

''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-Talk(en anglais). Par commodité tous les commentaires ultérieurs peuvent être ajoutés là.

Récupéré sur http://actux.eu.org/wiki/PmWikiFr/DocumentationGuidelines
Page mise à jour le 20/08/2009 13:31