Conseils de bon style

Voici quelques conseils sur la façon d’écrire une bonne page de wiki. Utilisez la page de discussion pour vos commentaires à ce sujet.

Structure de page

Commencez votre page par un en-tête de premier niveau avec un titre significatif.
Séparez votre texte en paragraphes en laissant une ligne vide entre eux. Un paragraphe moyen ne devrait pas avoir plus de 10 à 20 lignes.
Si votre texte fait plus que quelques paragraphes (de 3 à 5), coupez-le en sections en ajoutant des entêtes de niveau 2 à 5.
Quand votre texte fait plus de 2 ou 3 pages d’écran, mettez un court résumé du contenu de la page après le premier en-tête.
Si vous avez beaucoup de liens vers d’autres pages wiki ou vers des ressources externes, ajoutez une section spéciale avec d'autres références (voir ci-dessous).

Les mots seuls peuvent être mis en évidence soit en les soulignants, soit en les mettant gras, soit en les écrivant en lettres CAPITALES. Les court passages de textes peuvent être mis en évidence soit en italique, soit en gras.
Choisissez un style pour afficher la sortie du texte à l’écran comme des boutons ou des étiquettes de menu et utilisez-le uniformément. Ce pourrait être une bonne idée d'ajouter une page avec une explication de vos conventions de styles propres à votre wiki.
Utilisez les listes non triées pour les éléments qui sont indépendants les uns des autres. Si vous développez une explication, écrivez les phrases dans un ordre continu.
Utilisez avec parcimonie les notes de pied de page et seulement pour des remarques complémentaires très courtes. S'il y a beaucoup plus à dire sur un sujet spécifique, mettez-le sur une nouvelle page du wiki. Si vous voulez vous référer à d'autres sources d'informations (extérieures), utilisez plutôt des liens.
Les Tableaux peuvent améliorer considérablement la lisibilité de données structurées. Si vous insérez un tableau, assurez-vous qu'il ait des en-têtes significatifs pour chaque cellule et mettez une légende qui énonce clairement le contenu du tableau (par exemple “Tableau 1.2 : Distances moyennes entre les planètes”).

Utilisez des phrases bien construites et utilisez les articles pour les noms.
Commencez chaque phrase par une majuscule et terminez-la avec un point ou toute autre ponctuation appropriée.
Essayez d'écrire court, des phrases claires sans trop avoir recours à des explications de moindre importance. Quand vous pensez que vous avez terminé votre page, relisez-la encore et corrigez les phrases qui ont une structure excessivement compliquée.
Décidez de la façon dont vous voulez vous adresser au lecteur. Puisque DokuWiki est orienté vers l’écriture de documentation, vous devrez souvent donner des explications aux lecteurs, comment faire certaines choses. Vous pouvez utiliser la forme impérative (“faites ceci !”), la forme nous/vous (“puis nous/vous cliquons(ez) sur…”) ou la forme je (“j'ajoute alors le point à la barre, en utilisant…”). Ne mélangez pas ces formes.
Avant la sauvegarde examinez votre page pour déceler les fautes de grammaire ou d'orthographe. Si votre texte comporte beaucoup d'erreurs, il affaiblira la crédibilité de vos rapports, indépendamment de l’intérêt qu’ils peuvent avoir.
Développez votre propre style. Ne vous forcez pas à écrire avec un style qui ne vous convient pas. Il en résulterait un texte artificiel et désagréable à lire.

Quand vous utilisez un terme qui nécessite des explications supplémentaires, ajoutez une nouvelle page au wiki et faites un lien vers elle.
Vérifiez votre page avant de la terminer, ajoutez les liens vers les autres pages existantes du wiki pour les termes principaux de la page.
N'ajoutez pas un lien à chaque occurrence d'un terme spécifique. Faites-le sur la première occurrence rencontrée et ajoutez éventuellement un lien à la section de référence du terme.
Si vous ajoutez une ligne “Voir aussi :” à la fin de votre page. Faites des liens uniquement vers les pages du wiki qui sont étroitement liées au sujet de votre page.
Si vous voulez vous référer à des ressources externes qui donnent davantage d'informations à votre sujet ou que vous avez utilisées en écrivant votre page, ajoutez une section appelée “Références” ou “Plus d'informations” et fournissez une liste de liens. Indiquez dans votre lien l’objet du site auquel vous faites référence (par exemple “[site] d’autres conseils sur la reproduction des coccinelles.”).

“Une image dit plus que mille mots.” Elle peut même dire plus que ce que l’on aurait souhaité. Les humains ont moins tendance à remettre en cause l'authenticité des images que du langage. Une description textuelle courte est meilleure que rien du tout ou qu'une image imprécise.
Comme pour les tableaux, indiquez toujours une légende pour les images, qui énonce ce que vous voulez montrer avec l'image (par exemple “Image 3.2 : Photographie d'amateur montrant la reproduction des coccinelles.”)
Si vous n’êtes pas l’auteur de l'image, indiquez la source (probablement avec un lien) et le copyright.
Ne liez pas d'images de sites externes, à moins que vous ne soyez autorisé à le faire. En effet ceci vole de la largeur de bande au site accueillant l'image. Téléchargez plutôt l'image dans le wiki, si vous le pouvez.
Si l'image est plus grande que le tiers d'une page d'écran, utilisez un lien de redimensionnement pour afficher une vignette.

Page Conseils de bon style revue et corrigée de Dikuwiki créé par Philippe LAPEYRIE en 2006.