Guide stylistique openSUSE
|
Cet article est une ébauche ! Cet article a besoin d'être complété. Si vous pouvez y participer, merci de le faire en accord avec le Guide stylistique openSUSE. |
Cette page vise à fournir aux nouveaux venus des indications sur la manière de composer une page pour le wiki. Ces indications ne sont que des conseils que chacun doit adapter aux besoins - n'hésitez pas à ne pas suivre ces conseils si votre sujet le nécessite. Ils constituent cependant une bonne base de départ
Composer un article
Nombre de pages
Un article correspond à un document d'environ une page. Si il dépasse de beaucoup cette taille, il est préférable de le décomposer en plusieurs pages.
Organisation
Un article doit pouvoir être parcouru rapidement par des lecteurs qui ne savent pas s'il correspond à leur besoin. La lecture des titres ou de la table des matières doit déjà donner une idée du contenu de la page.
Il est également très utile de prévoir une "introduction" ou un "chapeau" résumant l'article.
Ensuite, un choix judicieux des sections (ou chapitres, paragraphes, parties) est important. Il est même souvent pertinent de commencer par indiquer ces titres, quitte à y faire des retouches ensuite.
Neutralité
Une page wiki va, au fil du temps, être modifiée par de nombreux auteurs. Ces modifications peuvent être des corrections d'orthographe et de typographie, mais également des ajouts ou des suppressions.
Rapidement la notion "d'auteur" de la page n'a plus guère de sens. Il est donc préférable de ne pas "personnaliser" l'article. Ne pas utiliser "je" mais "on", "certains utilisateurs"... écrire les phrases de telle sorte qu'elles s'adaptent à n'importe quel lecteur/auteur.
Pensez également que vous êtes sur un wiki essentiellement technique et consacré à Linux, et même à une version spécifique de Linux.
Toute page n'ayant aucun rapport avec l'objet du wiki (la conquête de la lune est pour demain), polémique (le système d'exploitation Fenêtre est ridiculement plus lent que...) ou grossier (é"'(-è_çà)=) sera sans doute éditée voire même effacée très vite.
Même si votre page est tout à fait dans l'objet du wiki, elle peut être polémique (la SUSE Linux 9.3 est bien meilleure que la version 8.2). Est considérée comme polémique une affirmation qui est soit inutile, soit insuffisamment ou non prouvée. N'oubliez pas que ce qui est vrai sur votre matériel peut être complètement faux sur le matériel d'un autre ou avec une utilisation différente de la vôtre.
Essayez, dans votre texte, de respecter l'opinion des autres. Précisez vos remarques, par exemple en citant le matériel utilisé pour les tests ou les conditions de ceux-ci. Soyez positif. Si vous citez un bug, essayez de donner les correctifs ou, au moins, le numéro de Bugzilla qui y fait référence.
Risque d'erreurs
Écrire un article lorsque l'on n'est pas tout à fait sûr de ce qu'il faut y mettre peut être une très bonne chose ou une très mauvaise.
Il faut absolument éviter tout ce qui pourrait détruire le matériel ou le système de votre lecteur trop confiant. Ne donnez pas d'instruction dangereuse que l'on pourrait copier/coller directement du wiki dans une console.
Si une telle instruction est nécessaire, placez-y un détail qui la rende invalide et donnez les instructions pour supprimer ce détail.
Par exemple :
Pour effacer totalement votre disque dur, connectez-vous en root et tapez
vous ne croyez pas que je vais vous dire comment faire une pareille bêtise ? si vous y tenez vraiment, lisez le manuel de "rm"
Par contre, cet article va attirer l'attention d'autres lecteurs qui vont l'améliorer. Placez-y la balise "à enrichir", il y a un modèle pour ça :
{{A compléter}}
La technique Mediawki/openSUSE
Utiliser votre page personnelle
Quand vous vous connectez sur openSUSE.org et que vous vous êtes identifié (c'est obligatoire pour écrire), vous voyez en haut de la page quelque chose comme ceci :
le lien le plus à gauche (ici jdd) est celui vers votre page personnelle. Attention, n'importe qui peut écrire sur cette page et n'importe qui peut la lire. Y écrire est faire preuve de mauvaise éducation (ou faire une erreur), pour vous écrire il faut utiliser "votre page de discussion" associée automatiquement à votre page personnelle.
Cette page personnelle est là pour vous permettre d'organiser votre travail avec le wiki. Vous pouvez, par exemple, y copier les liens vers les pages qui vous sont les plus utiles, comme ceci - ou encore ceci.
Créer un article
Pour créer un nouvel article, le plus simple est de créer un lien vers cet article avant de l'écrire. Si cet article est directement en relation avec un autre, créez ce lien directement dans l'autre page, sinon créez le dans votre page personnelle. Il suffit d'entrer en mode édition et de taper :
[[Titre de la nouvelle page]]
Les espaces sont autorisés, les lettres accentuées aussi.
Introduction
Si Mediawiki trouve au début de la page une partie de texte non précédée par un titre, il place ce texte avant la table des matières. C'est une façon très efficace d'écrire une introduction/résumé pour une page (comme sur la présente page).
Titres d'article
Le nom de votre article est en même temps son en-tête et le titre de la page, il n'est donc pas nécessaire de le répéter dans la page. N'utilisez pas d'abréviations, n'utilisez pas le format courant des wikis avec un mélange de minuscules et de majuscules. La syntaxe Modèle:nom du modèle est réservée au fonctionnement du wiki. On l'appelle "Espace de nom" et ces noms d'espace doivent être créés par l'administrateur pour fonctionner (et c'est assez délicat).
Pour plus de détails, voir ici.
Titres de sections
L'aide Mediawiki est fort bien rédigée.
L'utilisation des titres a beaucoup d'avantages.
- Il entraîne la création automatique d'une table des matières, ce qui vaut comme un résumé de la page ;
- il permet de modifier les sections ainsi créées une par une au lieu de modifier toute la page.
- Remarque
- il est tout à fait inutile de mettre des espaces entre les "==" et le texte du titre, ces espaces sont supprimés automatiquement à l'affichage.
Agrémentez votre texte
Utilisez les marques de formats de texte pour rendre votre texte plus agréable à lire. Par exemple, marquez les noms de fichiers :
<tt>texte technique</tt>
Utilisez les balises Mediawiki
Presque toutes les balises HTML sont acceptées (après tout, Mediawiki transforme votre texte en HTML pour qu'il soit lisible avec un navigateur), mais beaucoup de personnes préfèrent les balises Mediawiki. Essayez donc de les utiliser en priorité (voir paragraphe précédent).
Regardez aussi le code de quelques pages de ce wiki (en cliquant sur "modifier"), cela peut vous donner un point de départ.
Commentaires
Chaque page du wiki a une page de discussion. Utilisez-la sans hésiter. Ne mettez pas de commentaire dans le corps de l'article, au contraire, recopiez dans la page de discussion les parties que vous voulez commenter.
Si vous ne connaissez qu'une partie des réponses au problème que vous soulevez, utilisez le modèle {{Pages à compléter}}.
Si vous voulez communiquer avec d'autres rédacteurs potentiels, écrivez des commentaires invisibles aux lecteurs ordinaires. Pour cela entourer le texte à masquer par une balise de commentaire html <!-- et -->. Attention, on ne peut pas mettre de commentaire partout dans un wiki sans perturber la mise en page, faites l'essai.
Par exemple, ce qui suit :
hello <!--This is a comment.--> world
est affiché comme ceci :
- hello world
Alors que si vous modifiez la page vous verrez entre les deux mots un commentaire en anglais.
Modèles
Les modèles sont un outil relativement complexe, mais très commode. Les modèles les plus utiles sont ici.
Particularités du français
Les français ne font rien comme tout le monde...
- Il faut un espace à l'extérieur et pas d'espace à l'intérieur de tout ce qui ressemble à une parenthèse, soit {([-)]} ;
- Les caractères ;:!? doivent être précédés d'un espace (sauf quand ils sont listés ensemble, comme ici :-) et cet espace est un espace insécable qui s'écrit " " ;
- Il est facile de confondre {{}} et [[]] s'ils ne sont pas très gros. En général (en tout cas avec Mozilla ou Konqueror), Ctrl + permet de grossir l'affichage ;
- La langue français bénéficie d'un riche éventail de mots. Autant en profiter pour éviter les redondances inutiles, par exemple en employant un dictionnaire des synonymes ;
- Dans une liste (comme ici), le, premier caractère ne prends pas de majuscule et chaque ligne se termine par un ";" (précédé de , donc). Le dernier élément de la liste se termine en général par un point.