====== Guide éditorial (DRAFT) ====== ===== Plan ===== La documentation du produit et des modules suit la structure suivante : ==== Produit dynacase ==== La documentation de chaque version de dynacase est stockée dans un sous-répertoire comportant le numéro de la version. === /dynacase/ === Cette page ''/dynacase/'' contient la description du produit et en particulier les nouveautés de la version plus l'index des pages présentes dans ce répertoire : ====== 3.1 ====== Message d'entête. Contenu : {{indexmemu>3.1|navbar notoc msort}} Message de pied de page. === /dynacase//documentation === Un sous-répertoire documentation contiendra la documentation de cette version de dynacase Cette page ''/dynacase//documentation'' contient l'index des pages présentes dans ce répertoire : ====== Documentation ====== {{indexmenu>documentation|navbar notoc msort}} === /dynacase//documentation/introduction === La page ''introduction'' contient une description du produit {{indexmenu_n>1}} ====== Introduction ====== Description du produit... === /dynacase//documentation/pre-requis === La page ''pre-requis'' contient les pré-requis pour l'installation et l'utilisation du produit. {{indexmenu_n>2}} ====== Pré-requis ====== Pré-requis : ... === /dynacase//documentation/installation === La page ''installation'' contient la procédure d'installation du produit. Cette page décrit : * Les paramètres systèmes/PHP/etc. à appliquer * les paramètres demandés par control lors de l'installation du produit {{indexmenu_n>3}} ====== Installation ====== Procédure d'installation : ... === /dynacase//documentation/* === Autres pages. Positionner l'indexmenu_n > 3 par exemple : /dynacase//tutoriaux Un sous-répertoire tutoriaux contiendra les tutoriaux de cette version de dynacase Cette page ''/dynacase//tutoriaux'' contient l'index des pages présentes dans ce répertoire : {{indexmenu>tutoriaux|navbar notoc msort}} ==== Modules ==== La documentation de chaque modules de dynacase est stockée dans un sous-répertoire comportant le numéro de la version. === /modules === Cette page ''/modules'' référence les modules : Message d'entête. {{indexmenu>modules#1|tsort}} Message de pied de page. === /modules/ === Cette page ''/modules/'' contient l'index des versions du module : Message d'entête Version : {{indexmenu>foo|dsort}} Message de pied de page === /modules// === Cette page ''//'' contient l'index des pages présentes dans ce répertoire : Message d'entête Contenu : {{indexmemu>1.2.3|navbar notoc msort}} Message de pied de page === /modules///introduction === La page ''introduction'' contient une description du module. {{indexmenu_n>1}} Description du module... === /modules///pre-requis === La page ''pre-requis'' contient les pré-requis pour l'installation et l'utilisation du module. {{indexmenu_n>2}} Pré-requis : ... === /modules///installation === La page ''installation'' contient la procédure d'installation du module. Cette page décrit : * Les paramètres systèmes/PHP/etc. à appliquer * les paramètres demandés par control lors de l'installation du module {{indexmenu_n>3}} Procédure d'installation : ... === /modules///paramètres === La page ''paramètres'' décrit les paramètres Dynacase du module (i.e. Paramètres applicatifs). {{indexmenu_n>4}} Procédure d'installation : ... === /modules///* === Autres pages. Positionner l'indexmenu_n > 4 ===== Nouvelle version ===== Lors de la sortie d'une nouvelle version du produit ou d'un module, il faut : * Copier le répertoire N-1 du produit (ou module) dans un répertoire N * Changer les références à la version N-1 par la version N dans tous les fichiers de cette version du produit (ou module) ====== Guide éditorial (OLD) ====== Ce guide est un ensemble de règles à respecter lors de votre contribution à ce wiki, que ce soit par la création ou la mise à jour d'une page. ===== Organisation générale et cohérence ===== Merci de le lire au moins une fois en entier avant de contribuer à ce wiki. ==== Respect du plan ==== Le [[edito:index#plan|plan]] de ce wiki veut le rendre accessible à tous, habitué de freedom ou néophyte, développeur ou curieux, vous, nous.... Afin de garantir cette accessibilité, il est important de bien positionner votre page dans l'[[edito:index#plan|arborescence]] du site. Notez que la façon dont les pages s'agencent est décrite [[edito:index#organisation_generale|à la suite du plan]]. ==== Identification du type de contenu ==== De même, afin que le lecteur sache tout de suite s'il a affaire à une page technique ou à une page générale, il est important de ne pas mélanger ces 2 types de contenu: n'hésitez pas à créer 2 pages, et à faire des liens entre elles, tout le monde s'y retrouvera mieux en fonction de son besoin. ==== Titre et plan des pages ==== Lorsque vous créez une page, donnez lui un nom explicite, ainsi qu'un titre lui aussi compréhensible. Cela simplifiera les recherches. Pensez également à créer des sections avec des titres de différents niveaux, afin de structurer votre contenu: il n'y a rien de plus pénible que de devoir lire une page complète pour savoir si elle est susceptible de contenir l'information recherchée. (Mais n'abusez pas non plus, trop de sections rendent le texte illisible...) ===== Modifications ===== Vos contributions sont les bienvenues, et vous êtes libres de modifier le contenu des pages ou d'en créer (vous êtes mêmes invités à le faire en cas d'information incomplète ou erronée), mais rappelez-vous que vos modifications ne sont pas anodines. En cas de doute, n'hésitez pas à consulter [[#ajouter un lien vers la section concernée du forum |la partie du forum consacrée à la rédaction du wiki]]. FIXME ==== Page sur les nœuds ==== Eviter de mettre le texte d'un nœud dans une page sous un nœud de même nom pour éviter les boublons dans l'URL comme dans [[:contribution:contribution]] avec ''/contribution/contribution'' : éditer et mettre le texte directement sur le nœud [[:contribution]] pour avoir le contenu dans ''/contribution''. ==== Lien entre pages ==== Les liens doivent de préférence être relatifs lorsqu'il est nécessaire d'assurer la cohérence des informations lors de l'évolution du wiki. Par exemple, si les différentes pages sont liées à une même version, en les dupliquant et si les liens sont relatifs, il ne sera pas nécessaire de reprendre l'ensemble de ces liens. ==== Mise à jour d'une page ==== Lors de la mise à jour d'une page, pensez à bien renseigner le résumé de cette mise à jour. Cela permet de suivre l'historique du site au moyen des flux RSS. Assurez-vous également de bien modifier la bonne page, et que cette modification est légitime (Rappelez-vous que dans certains cas, il est plus judicieux de créer une page que d'en surcharger une autre). ==== Création d'une page ==== Pour créer une page: - il faut commencer par créer un lien vers cette page ((Cela permet d'éviter le problème des pages orphelines.)). - il faut ensuite vous rendre sur cette page et cliquer sur le lien "créer cette page" - pensez ensuite à prévisualiser la page créée au moyen du bouton "aperçu" - sauvegardez. Assurez-vous de mettre la page au bon endroit, et demandez-vous si cette création est légitime (Rappelez-vous que dans certains cas, il est plus judicieux de compléter une page exsistante que d'en créer une nouvelle qui n'a aucun sens par elle-même). Imaginions, par exemple que vous soyez sur la page [[contribution:wishlist|Wishlist]] et que vous vouliez ajouter la page [[Portage oracle]]. Vous éditez donc la page [[Wishlist|contribution:wishlist]] et y ajoutez le lien au moyen de la syntaxe ((Pour plus de précisions sur la syntaxe, reportez vous à la [[wiki:syntax|page qui y est consacrée]])): %%[[contribution:wishlist:portage_oracle|Portage oracle]]%%, puis sauvegardez votre modification en pensant à bien ajouter le commentaire correspondant. Notez ici: - tant que la page de destination n'est pas créée, le lien est rouge - L'endroit où j'ai ajouté cette page est important, comme expliqué aux paragraphes précédents: ici, elle est ajoutée en tant que fille de la partie wishlist Vous pouvez ensuite suivre le lien créé, et cliquer sur "Créer cette page" (en bas de la page). Il ne vous reste alors plus qu'à rédiger... ==== Déplacement de contenu ==== C'est probablement la moins anodine de ces opérations. Lorsque vous déplacez du contenu, soyez clair sur ce déplacement: ajoutez un lien à la place du contenu supprimé, et éventuellement une note là où le contenu est inséré. Cela permettra à ceux qui avaient l'habitude de venir à un endroit de ne pas être (trop) perturbés par ce changement. ===== Mise en forme ===== La mise en forme est un élément important de vos pages: Plus la mise en forme sera claire, plus vite les lecteurs auront accès à l'information. ==== Plugins disponibles ==== Les plugins qui sont disponibles pour vous aider dans la mise en forme sont les suivants: - **wrap**: http://www.dokuwiki.org/plugin:wrap\\ Il permet de définir des boites de texte === Utilisez ces plugins === Ces plugins rendent votre texte plus clair, et plus agréable à lire. === N'abusez pas de ces plugins === Trop utilisés, ces plugins rendent votre texte illisible! ==== Versions ==== Lorsque ce que vous écrivez concerne une version spécifique de freedom, il est important de le préciser de façon claire: * Les contenus freedom 2.* et 3.* doivent être sur des pages distinctes * lorsque les spécificités liées à une version ne portent que sur quelques détails, il n'est pas nécessaire de créer une nouvelle page, et l'utilisation des plugins pré-cités peut rendre les choses claires. ===== Qualité du contenu ===== Ce n'est pas un exercice de style, et vous n'êtes pas évalués sur vos contributions, mais souvenez-vous que: - Vos contributions seront lues par beaucoup de monde - Cette documentation est une passerelle pour les gens qui découvrent ou utilisent freedom. Il vous est donc demandé de faire un minimum d'effort quant à la rédaction (une bonne orthographe et des phrases compréhensibles sont toujours agréables) et de ne pas hésiter à corriger les quelques coquilles, typos et autres qui peuvent se glisser dans les contributions de chacun. Enfin, lorsque vous avez un doute sur ce que vous rédigez - signalez-le dans votre résumé - indiquez-le sur la page - demandez qu'on vous relise, ou des précisions sur le forum.