Guide de documentation du DHIS2

- DHIS 2 Documentation System Overview - + Guide de documentation du DHIS2 +

+ Aperçu du système de documentation du DHIS 2 + Le DHIS 2 est un système de gestion d'informations agrégées, basé sur le web, qui bénéficie d'un développement très actif. Compte tenu de la nature modulaire de son système, sa base étendue d'utilisateurs et la nature globale de son développement, la mise en place d'une documentation complète était devenue nécessaire pour l'accompagner. C'est ainsi qu'une réflexion approfondie sur la nécessité d'une documentation du DHIS 2 a été menée au préalable, et que le choix d'utiliser DocBook pour conduire ce projet de documentation a été fait. Ce document ne va pas s'étendre sur les mérites relatifs de la plate-forme DocBook, mais veut plutôt servir de guide succinct à son emploi par les utilisateurs et développeurs de DHIS 2. - Store2007 - DocBook + Store2007DocBook est un système complet basé sur le XML destiné à la création de livres, documents généraux et autres documents techniques. Il est maintenu par OASIS . -

- Introduction - +

+ Introduction + L'un des principaux avantages de DocBook est la séparation complète qu'il opère entre le contenu et la présentation. DocBook est un format XML pur, et il est bien documenté. Nous croyons qu'un très petit sous-ensemble de ses fonctionnalités sera nécessaire à la réalisation d'une documentation de grande qualité du DHIS. Il contient environ 400 balises qui correspondent à quasiment tous les niveaux d'exigence des documentations techniques, mais en réalité, il n'y aura besoin que d'une petite douzaine de ces éléments pour réaliser une documentation de grande qualité du DHIS 2, aussi bien pour la production de documents destinés à l'impression que pour la production de documents consultables en ligne comme les pages HTML ou les pages d'aide intégrées à l'application elle-même. Il existe de nombreuses manières de créer des fichiers DocBook. Une liste assez exhaustive de ces possibilités est décrite ici . Il est présentement recommandé d'utiliser l'éditeur WYSIWYG Syntext Serna Free pour l'édition des fichiers sources DocBook. En principe, toutefois, n'importe quel éditeur de texte ou de fichiers XML peut être utilisé pour l'édition de fichiers DocBook. - - Il est déconseillé d'utiliser l'éditeur XMLmind XML Editor Personal Edition (également connu sous le nom de XXE Personal), vu que cet éditeur ajoute "discrètement" des espaces inutiles et d'autres agrémentations au fichier source DocBook, rendant ainsi la création collaborative de documents fortement difficile. - - + + Il est déconseillé d'utiliser l'éditeur XMLmind XML Editor Personal Edition (également connu sous le nom de XXE Personal), vu que cet éditeur ajoute "discrètement" des espaces inutiles et d'autres agrémentations au fichier source DocBook, rendant ainsi la création collaborative de documents fortement difficile. + + L'un des concepts clés à garder à l'esprit lors de la création de documentation sous DocBook, ou sous d'autres formats neutres de présentation d'information, est que le contenu du document doit être pris en considération en premier lieu. La présentation du document s'effectue au cours d'une étape ultérieure, au moment où le document va être transformé en différents formats comme le HTML et le PDF. Il est à cet effet important de faire en sorte que le document soit bien organisé et structuré, avec les balises DocBook appropriées, et la bonne prise en compte des élements structurels de sa composition. - + Il est considéré comme une bonne attitude de scinder votre document en plusieurs sections en utilisant la balise "sect", ou un élement de section. Les éléments de section peuvent aussi être imbriqués les uns à l'intérieur des autres, comme "Section 1" et "Section 2". C'est le même concept que celui utilisé par Microsoft Word ou d'autres logiciels de traitement de texte. DocBook se chargera automatiquement de numéroter les sections au cours de la production du document. Les deux autres éléments sont la balise "itemizedlist" et "numberedlist". Ils sont presque identiques, mais la balise "itemizedlist" correspond à des listes à puce, tandis que la balise "numberedlist" fait référence à des éléments listés séquentiellement avec des numéros. Les autres éléments clés sont les balises "screenshot" et "table" qui parlent d'eux-mêmes. -

- Introduction à Launchpad - +

+ Introduction à Launchpad + Actuellement, le système de documentation est une partie du code source et il est hébergé chez Launchpad . Launchpad est une plateforme collaborative qui permet à plusieurs personnes de travailler sur des projets de logiciels de manière collaborative. Pour rendre cela possible, un système de contrôle de version est nécessaire, son rôle étant de gérer toutes les modifications que plusieurs utilisateurs pourraient effectuer. Launchpad utilise le système de contrôle de version Bazaar . Bien qu'il soit hors de portée de ce document de décrire les fonctionnalités de Bazaar , les utilisateurs qui souhaitent créer des documents gagneraient à avoir au moins une compréhension de base de la façon dont ce système fonctionne. Un guide de base est fourni dans la section suivante. - + Afin de commencer à ajouter ou éditer la documentation, vous devrez d'abord effectuer une vérification du code source. Si vous n'avez pas déjà un identifiant sous Launchpad, vous devrez d'abord en avoir un. Vous pouvez le faire sur ce lien. Une fois que vous vous serez enregistré sur Launchpad, vous devrez solliciter l'accès auprès du groupe des rédacteurs de documents du DHIS 2, le groupe baptisé dhis2-documenters. Pour ce faire, connectez-vous à Launchpad, puis sollicitez un accès sur ce lien. Votre demande devra d'abord être aprouvée par le groupe d'administrateurs. Une fois que cet accès vous sera accordé, il vous sera possible de soumettre vos modifications sur l'arbre de documentation et d'envoyer ou recevoir des messages sur les groupes de discussion. -

- Obtenir le fichier source de la documentation - +

+ Obtenir le fichier source de la documentation + Afin de modifier la documentation, vous aurez besoin de télécharger les pages sources de la documentation sur votre ordinateur. Launchpad utilise un système de contrôle de version connue sous le nom de bzr. Il existe différentes méthodes pour faire fonctionner Bazaar sur votre système, en fonction du système d'exploitation que vous utilisez. Un bon guide étape-par-étape pour le système d’exploitation Microsoft peut être visualisé ici. Si vous utilisez Linux, vous aurez besoin d’installer bzr sur votre système à l’aide de votre gestionnaire de paquets ou du code source. - Une fois que vous aurez installé bzr sur votre système, vous aurez besoin de télécharger le code source de la documentation. Vous pouvez suivre la procedure suivante: - - - Assurez-vous que vous avez Bazaar correctement installé. - - - + Une fois que vous aurez installé bzr sur votre système, vous aurez besoin de télécharger le code source de la documentation. Vous pouvez suivre la procedure suivante: + + + Assurez-vous que vous avez Bazaar correctement installé. + + + Démarrer Bazaar en faisant un clic droit sur le dossier si vous utilisez Windows ou en sélectionnant Bzr Ici . Si vous utilisez Linux, vous pouvez créer un dossier pour contenir le code source de la documentation. Vous pouvez placer les fichiers sources de la documentation où vous voulez. - - - + + + Pour télécharger la dernière version de la documentation du projet DHIS 2, saisissez : bzr checkout lp:~dhis2-documenters/dhis2/dhis2-docbook-docs Si vous utilisez Linux, ou, également, si vous utilisez @@ -62,15 +61,15 @@ lp:~dhis2-documenters/dhis2/dhis2-docbook-docs " - - - Le téléchargement devrait alors commencer et tous les fichiers sources de la documentation seront téléchargés dans le dossier que vous aurez précisé. - - -

- Modifier la documentation - + + + Le téléchargement devrait alors commencer et tous les fichiers sources de la documentation seront téléchargés dans le dossier que vous aurez précisé. + + +

+ Modifier la documentation + Une fois que vous aurez téléchargé les fichiers sources, vous obtiendrez une série de dossiers à l’intérieur du dossier dhis2-docbook-docs . Tous les documents devraient être dans le dossier dhis2-docbook-docs/src/docbkx/XX folder. Noter que @@ -80,71 +79,74 @@ . Placez tous les fichiers images qui devront être liés à votre document dans le dossier /dhis2-docbook-docs/src/docbkx/XX/resources/images et utilisez les pour insérer des liens à l’intérieur de votre document DocBook en utilisant un lien de fichier relatif. Lorsque le document est généré, dans une étape séparée, les images seront automatiquement copiées pendant le processus de genèse. -

- Bibliographie du DHIS2 - +

+ Bibliographie du DHIS2 + DHIS2 a un vaste ensemble de documentation académique qui peut servir de ressources précieuses pendant les implémentations, les propositions de projets et pour des lectures plus approfondies que ce qui est mis dans un mode d'emploi général. Une bibliographie spécialisée a été ajoutée au code source de l’application. BibTeX est un langage specialisé qui est largement utilisé dans le monde académique pour gérer les bases de données bibliographiques. Un grand nombre d’utilitaires libres et open source sont en mesure de travailler avec BibTeX. Actuellement, l’utilitaire de prédilection pour gérer la bibliographie de DHIS 2 est JabRef . - + Pour commencer avec la bibliographie, téléchargez une copie de JabRef et ouvrez le fichier /src/bibliography/dhis2_bibliography.bib file . . Ajoutez quelques nouvelles references, puis exportez la bibliographie dans le fichier /src/docbkx/en/dhis2_bibliography.xml , en utilisant le format d’exportation DocBook 4.4. La bibliographie mise à jour sera automatiquement incluse dans la documentation après que vous ayez soumis (via l’argument de commande commit) vos modifications. -

- Utilisation des images - +

+ Utilisation des images + Les captures d'écran sont très utiles pour fournir des informations aux utilisateurs sur la façon dont certaines actions doivent être effectuées. DocBook ne possède pas de mécanismes internes pour savoir exactement comment une image doit être rendue dans le document final. Par conséquent, il est nécessaire de fournir des instructions par l'intermédiaire d’attributs d'élément. Le fragment de code XML suivant montre comment une image peut être définie pour occuper 80% de la largeur de la page disponible. Pour des captures d'écran affichées au format paysage, ceci semble être une valeur indiquée. Vous devrez peut-être faire un peu d’essais pour obtenir la largeur idéale de votre image. Alternativement, vous pouvez modifier la résolution de l'image elle-même, afin d'obtenir une taille appropriée pendant le rendu. - - Ecran de la page de connexion à DHIS 2 - - - - - - - - Pour les autres images, selon leur taille, une valeur différente pourrait être nécessaire. Si vous ne précisez pas la largeur de votre image, et que leur taille réelle est plus grande que l’écran disponible, l’image pourrait déborder dans certains documents qui utilisent une largeur fixe, comme les PDF. + + + Ecran de la page de connexion à DHIS 2 + + + + + + + + Pour les autres images, selon leur taille, une valeur différente pourrait être nécessaire. Si vous ne précisez pas la largeur de votre image, et que leur taille réelle est plus grande que l’écran disponible, l’image pourrait déborder dans certains documents qui utilisent une largeur fixe, comme les PDF. -

- Relier les documents entre eux - +

+ Relier les documents entre eux + DocBook offre un cadre modulaire où de nombreux documents séparés peuvent être reliés entre eux dans un document maître. Des portions de différents documents peuvent également être réutilisées dans différents contextes. Il est donc important de déterminer si votre document doit être construit comme un article ou comme un chapitre. Les chapitres sont essentiellement des parties d'un livre, et peuvent donc être reliés entre eux dans un document plus facilement. Les articles sont essentiellement des documents autonomes, mais ils peuvent aussi être assemblés dans un document plus large. -Should you wish to link several articles together into a book, DocBook provides a mechanism to assign an id to a section. In the example below, a section has been assigned an id. This id must be unique within the document. + Should you wish to link several articles together into a book, DocBook provides a mechanism to assign an id to a section. In the example below, a section has been assigned an id. This id must be unique within the document. Si vous souhaitez relier plusieurs articles ensemble dans un livre, DocBook fournit un mécanisme pour attribuer un identifiant à une section. Dans l'exemple ci-dessous, un identifiant a été attribué à une section. Cet id doit être unique dans le document. - - <section id="mod2_1"> + + <section id="mod2_1"> <title>Démarrer avec DHIS2</title> .... - - + + <chapter> <title>Démarrer avec DHIS2</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_mod2.xml" xpointer="mod2_1" encoding="UTF-8"/> ... - Notez que le nom de fichier et son identifiant ont été attributes dans le document parent, faisant une reference au document courant (href) et au fragment particulier du document enfant qui pourrait être référencé dans le document parent (xpointer). - - Inclure des chapitres dans un document est un processus très simple. L’exemple suivant illustre comment faire : - - - - Dans ce cas, il n’est pas nécessaire de faire explicitement une reference à une partie du document, à moins de vouloir inclure une partie du chapitre. Si vous voulez utiliser une section du chapitre, vous pouvez attribuer un id à cette section, puis référencer cette section par le biais d’un xpointer. -

- Gérer une documentation en langues multiples - + Notez que le nom de fichier et son identifiant ont été attributes dans le document parent, faisant une reference au document courant (href) et au fragment particulier du document enfant qui pourrait être référencé dans le document parent (xpointer). + + Inclure des chapitres dans un document est un processus très simple. L’exemple suivant illustre comment faire : + + + + + + Dans ce cas, il n’est pas nécessaire de faire explicitement une reference à une partie du document, à moins de vouloir inclure une partie du chapitre. Si vous voulez utiliser une section du chapitre, vous pouvez attribuer un id à cette section, puis référencer cette section par le biais d’un xpointer. +

+ Gérer une documentation en langues multiples + La structure du repertoire de la documentation a été créée dans le but de faciliter la creation de documents dans n’importe quelle langue. Si vous voulez créer un nouvel ensemble de documents dans un langage donné, veuillez simplement créer un nouveau répertoire dans le dossier dhis2-docbook-docs/src/docbkx/ . Assurez-vous d’utiliser le code ISO 639-1 de la langue pour laquelle vous allez créer les documents. Une liste complete de ces codes peut être trouvée @@ -153,21 +155,21 @@ pom.xml dans le dossier principal dhis2-docbook-docs. Si vous n’êtes pas sûrs de quelles modifications doivent être apportées à ce fichier, demandez d’abord à la liste de diffusion, étant donné que ce fichier contrôle la génération de toute la documentation. -

- Construire la documentation - L’un des avantages principaux du format DocBook, c’est que les fichiers sources de la documentation peuvent être transformés en une grande variété de formats, dont HML, HTML par parties, XHTML, PDF, et un grand nombre d’autres formats.Il y’a une grande variété d’utilitaires quis sont en mesure d’effectuer cette tâche. Pour simplifier, le code source XML du document va être transformé en utilisant les feuilles de style standards XSL de DocBook dans le format souhaité. La liste complète des outils capables de transformés DocBook ne sera pas listée ici, mais quelques exemples sont fournis ci-dessous. +

+ Construire la documentation + L’un des avantages principaux du format DocBook, c’est que les fichiers sources de la documentation peuvent être transformés en une grande variété de formats, dont HML, HTML par parties, XHTML, PDF, et un grand nombre d’autres formats.Il y’a une grande variété d’utilitaires quis sont en mesure d’effectuer cette tâche. Pour simplifier, le code source XML du document va être transformé en utilisant les feuilles de style standards XSL de DocBook dans le format souhaité. La liste complète des outils capables de transformés DocBook ne sera pas listée ici, mais quelques exemples sont fournis ci-dessous. - + Les dernières constructions de la documentation sont disponibles sur le site web du DHIS2 . Les dernières versions instantanées sont disponibles à travers leur integration continue dans le serveur ici . -

- Construire la documentation à l’aide d’Apache Maven - +

+ Construire la documentation à l’aide d’Apache Maven + Afin de transformer les fichiers sources de la documentation en different formats, comme HTML ou PDF, vous aurez besoin d’installer le programme Apache Maven. Vous pouvez obtenir une copie ici ou en l’installant or by installing par le biais du gestionnaire de parquets si vous utilisez Linux. Veuillez juste exécuter la commande @@ -179,12 +181,12 @@ dhis2-docbook-docs/target/docbkx . -

- Construire à l’aide de xmlto - - xmlto +

+ Construire à l’aide de xmlto + + xmlto est un utilitaire utile disponible sur les plateformes Linux pour transformer les documents DocBook en plusieurs formats different. Plus d’informations sur le paquet peuvent être trouvés ici . Si vous ne voulez pas utiliser Apache Maven pour une raison quelconque, vous pouvez installer @@ -194,68 +196,65 @@ vous pouvez juste executer la commande xmlto - html - fichier_a_transformer - + htmlfichier_a_transformer où le paramètre fichier_a_transformer est le meme que celui du fichier que vous voulez transformer. Il y’a plusieurs autres formats disponibles, comme PDF, PS, JavaHelp et d’autres. -

- Confirmer vos changements sur Launchpad - +

+ Confirmer vos changements sur Launchpad + Une fois que vous avez fini de modifier votre document, vous devez confirmer vos modifications dans Launchpad. Ouvrez une invite de commande sous Windows ou une console sur Linux, et accédez au dossier où vous avez placé votre documentation. Si vous avez ajouté de nouveaux fichiers ou des dossiers à votre référentiel local, vous devrez les ajouter à l’arborescence source avec la commande bzr add , suivie du dossier ou du nom de (s) fichier (s) que vous avez ajouté (s). Une fois que vous avez ajouté tous vos nouveaux fichiers, vous devez mettre à jour le référentiel local pour vous assurer qu’il n'y a pas de conflits à l'aide de la commande suivante - bzr update - - + bzr update + . S’il y’a des conflits, bazaar va vous les notifer. Vos conflits peuvent aussi être listés en utilisant la commande bzr conflicts . S’il y’a des conflits dans un fichier, bazaar va créer trios versions de ce fichier : - - - - nomfichier.BASE - - - - - nomfichier.THIS - - - - - nomfichier.OTHER - - - - + + + + nomfichier.BASE + + + + + nomfichier.THIS + + + + + nomfichier.OTHER + + + + Ces fichiers correspondent respectivement aux parties communes au fichier, à la version locale et à la version sur le. Ces fichiers vont contenir des marqueurs pour indiquer les zones en conflit. Après la résolution des conflits en éditant chaque fichier et en supprimant les marqueurs de conflit, utiliser la commande bzr resolve . Cela va indiquer bazaar que les conflits ont été resoles, et procéder à la suppression des fichiers BASE, THIS, et OTHER. - Une fois votre code source mis à jour et les conflits resoles, vous pouvez confirmer vos modifications avec un message d’information concernant les modifications que vous avez effectuées: - -

- - bzr commit -m "Création de la traduction de la documentation en Amharique" - -

- - - + Une fois votre code source mis à jour et les conflits resoles, vous pouvez confirmer vos modifications avec un message d’information concernant les modifications que vous avez effectuées: + +

+ + bzr commit -m "Création de la traduction de la documentation en Amharique" + +

+ + + N’effectuez jamais une confirmation du code en utilisant bzr push , étant donné que cette commande va écraser tous les changements sur le depot et que tous les historiques de revision seront perdus. - - + + Si vous avez des questions, ou trouvez que vous n’arrivez pas à commencer, veuillez juste envoyer un email avec une description de votre problem à l’adresse dhis2-documenters@lists.launchpad.net . -

- +