Archive:Fr FR/ProjetDocs/EcrireAvecLeWiki

Ecrire Avec Le Wiki

Cette page décrit les problèmes spécifique en utilisant le Wiki pour écrire des tutoriaux et chapitres pour de grand travaux qui sont en voie d'être publié, comme la Documentation Fedora . Cette page s'étoffe et change, ainsi les idées d'origine sont remplacées par de nouvelles

File:WikiGraphics Fedora Design.png

Table of Contents

fr_FR/ProjetDocs/EcrireAvecLeWiki

Consultez la page WikiEdition pour trouver des conseils sur comment débuter à écrire avec le Wiki.

L'objectif principal de ces consignes supplémentaires est de vous aider à nous assurer que votre brouillon soit aisément converti au format DocBook, le format utilisé par les copies maîtresses de la Documentaion Fedora.

Les balises du wiki peuvent être différentes ici
À cause de problèmes découverts sur la méthode de conversion du wiki vers XML, nous mettons à jour constamment les pratiques d'utilisation des balises des zones du wiki telle que: Docs/Beats et Docs/Drafts . En général, nous essayons d'indiquer les changements dans [fr_FR/WikiEdition: WikiEdition] en particulier dans WikiEditing#Marking_Technical_Terms . Quelquefois, nous avons besoin de créer une exception à une règle. Cela arrive généralement lorsque le balisage du wiki est utilisé à des fins d'apparences, mais cela rend le code XML peu élégant.

Vous trouverez ci-dessous une vue d'ensemble sur comment travailler avec un Brouillon :

Règle d'or

Traitez les documents des autres comme si c'était les vôtres.

Comme l'accès CVS, tout membre du groupe DocWriterGroup possède les droits d'édition complet à l'arbre Docs/Drafts . Si vous vous apprétez à faire une modification importante sur le document d'une autre personne, demandez-lui au préalable son accord.

Créez chaque page avec un nom complet

Le Wiki MoinMoin traite les chemins d'accès en tant que le nom de page. Cela signifie que vous devez écrire une nouvelle page en créant un lien avec le chemin complet.

[[/Docs/Drafts/MaNouvellePage|  Nom long de la page]] 

Cela créé la page /Docs/Drafts/MaNouvellePage, qui sera une page différente de /MaNouvellePage et MoinMoin ne met en aucun cas les deux pages en relation.

Pour les même raisons, vous devez toujours utiliser les chemins d'accès complet lorsque vous créez les liens dans ce Wiki.

Pour créer un document Brouillon pour le projet documentation, créez le lien sur la page des brouillons .

Si vous désirez utiliser le Wiki pour créer de la documentation, envoyez un email à la liste de diffusion du Projet de Documentation afin d'être ajouté au groupe DocWritersGroup.

Utilisez une page unique par chapitre ou tutoriel

Chaque page du Wiki deviendra un fichier XML unique lorsqu'il sera exporté au format DocBook. Notre utilisation du format DocBook est la suivante:

• Un livre = un fichier parent qui appelle la préface, les chapitres et les appendices.
• Un chapitre = un fichier.
• Une section = une <section> comprise dans un fichier.
• Un article/tutoriel = un fichier contenant une section ou plus.

Pour suivre cet exemple dans le Wiki:

• Un livre = une page wiki parent qui est le sommaire de toute les chapitres.
• Un chapitre = une page Wiki, avec une section ou plus.
• Une section = une partie de page marquée par les symboles = =, == ==, etc de chaque coté du titre.
• Un article/tutoriel = un page unique contenant une section ou plus.

Par exemple:

• Docs/Drafts/SELinuxHowTo -- Le livre contient un sommaire
• Docs/Drafts/SELinuxHowTo/WritingPolicy -- un chapitre dans le livre

Débutez la page principale du document avec un sommaire

Le sommaire fournit des informations basiques pour les lecteurs et contributeurs du document. Le sommaire reste cohérent même si le contenu du document change. Remplir le sommaire peut également vous aider en clarifiant le champ d'application et l'objectif de votre document.

Les sommaires sont seulement pour les brouillons. Ces blocs sont supprimés des documents finaux. Ils existent sur les brouillons pour aider les auteurs et les relecteurs travaillant sur des documents incomplets.

Sélectionnez l'option Show Raw Text du menu déroulant More Actions sur la barre latérale, et copiez tout le texte situé entre les lignes START et END en haut de votre document.

Remplissez le sommaire avec les éléments de votre document. Regardez le sommaire des Brouillons existant pour exemples.

DEBUT DU SOMMAIRE

CECI EST UN BROUILLON, À UTILISER UNIQUEMENT PAR LES AUTEURS DE LA DOCUMENTATION ET LES ÉDITEURS. NE VOUS Y FIEZ PAS TANT QUE CET AVERTISSEMENT APPARAÎT ET JUSQU'À CE QUE LE DOCUMENT FINAL SOIT PUBLIÉ

Sommaire de la documentation:

Objectif:

Destinataire du document:

Assumption:

Documents liés:

Auteur principal:

---

FIN DU SOMMAIRE

Ci-dessous quelques explications pour chaque sections :

Objectif : Un bref résumé de ce que le document explique ou décrit.

Audience : Les gens à qui vous espérez que la lecture de ce document sera bénéfique. Décrivez les circonstance de l'utilisation de cette documentaion, plutôt que de les catégoriser. "Utilisateurs souhaitant faire fonctionner un serveur Web sur leur système Fedora" est un bon exemple d'audience, "administrateurs" ou "développeurs" sont des termes trop vagues.

Assumptions : Indiquez les conditions initiale du système, et tout prérequis nécessaire au lecteur. Vous devez toujours supposer une installation par défaut de Fedora (spécifiez le type d'installation : Desktop, station de travail ou serveur) et précisez comment installer tout logiciel additionnel requis par le document lui-même. L'autre hypothèse est le type de compte que devra utiliser l'utilisateur sur le système - dans la plupart des cas on supposera que le lecteur utilise un compte avec les valeurs par défaut (non root). Toujours spécifier si le lecteur devra utiliser le compte & le mot de passe root du système.

Documents liés : Les autres documents sur le Wiki ou publiés sur internet que vous pensez pertinent à votre document. En particulier, listez les site en relation avec le Projet Documentation Fedora et les projets de documentaion Linux que vous connaissez. Cette section aide à minimiser les efforts aussi bien que fournir un ensemble de références utiles.

Auteur principal : Votre nom d'utilisateur du Wiki. Tout auteur peut faire de petites modifications, mais de grands changements doivent être discutés avec l'auteur principal

Tous les éléments du sommaire changeront et grandiront tant que le document sera développé - vous devriez compléter chaque éléments du mieux que vous pouvez, et les modifier toutes les fois que cela vous semblera nécessaire.

N'oubliez pas de vous abonner à votre page !

Abonnez-vous à votre page afin d'être sûr de recevoir un email chaque fois qu'une autre personne met à jour votre page.

Pour souscrire à une page, cliquez sur le lien 's'abonner sur la barre d'outils (barre lattérale?!).

Utilisez des sections

Les Sections comme celle-ci sont faciles à convertir au format DocBook. Utilisez-les librement. Pour des gros documents, créez une page au-dessous de la page principale pour chaque chapitre ou section.

L'en-tête du document utilise un ensemble de "signes égal". Chaque en-tête de section utilise deux groupes de "signes égal". L'en-tête pour toute sous-section utilise trois groupes de "signes égal".

= Entête du document =
== Entête section deux ==
=== Entête sous-section ===

Les sections vides devraient être évitées

Tous les liens doivent être des URLs complètes

Les pages normales du Wiki convertissent les NomWiki en liens valides. Une fois que le document à été converti au format DocBook, ces liens deviennent invalides. Pour cette raison, écrivez tous les liens vers les autres pages et les sites Internet comme liens externes - avec une URL complète sur une ligne séparée du texte.

Par exemple, écrivez le lien vers la FAQ du Wiki de cette manière: FAQ

Suivez les directives liées au style

Le Guide de Documentaion Fedora fournit un chapitre sur le bon style d'écriture :

• http://fedora.redhat.com/docs/documentation-guide/ch-style.html

Ces instructions ne seront pas bénéfiques qu'à vos lecteurs, mais elles aideront aussi les collaborateurs, les éditeurs et les traducteurs qui convertissent les document originaux en d'autres langues.

Exceptions aux règles des balises du Wiki

• Do not indent admonitions
• Do not indent code blocks
• Do not indent tables (admonitions)

Choses à éviter

Certaines fonctionnalités de MoinMoin ne sont pas aisément convertibles au format DocBook. S'il vous plaît, évitez les choses suivantes :

• Les notes de bas de page, ex. : la balise FootNote.
• Les macros telles que l'objet Table of Contents, dans les chapitres ou sections.
• Les liens courts vers d'autre pages du Wiki ex. : LienVersUneAutrePage

Tous les liens ci-dessus ne sont valides que pour les documents incorporés au Wiki.

La fonctionnalité d'exportaion au format DocBook échoue sur MoinMoin 1.3.5 si une note de bas de page FootNote existe.

Informations suplémentaires

• HelpForBeginners permet d'appréhender le Wiki.
• HelpOnEditing décrit le maniement des balises utilisées par MoinMoin.
• Fondamentaux de la documentaion technique dans le Guide de la Documentation Fedora.
• Outils d'écriture dans le Guide de la Documentation Fedora.
• Projet de Documentation Fedora