Guía para la Documentación de DHIS2

Una panorámica del sistema de documentación de DHIS 2 - DHIS 2 is a web-based aggregate information management system under very active development. Given the modular nature of the system, its wide user base and distributed, global nature of development, a comprehensive documentation system is required. An in-depth discussion of the need for documentation of DHIS 2 has been considered previously.Store2007 DocBook is a comprehensive XML based system for creation of books, papers and other technical documents maintained by OASIS . + DHIS2 es un sistema web de gestión de información agregada que está en continuo desarrollo. Dada la naturaleza modular del sistema, su distribución y foco en los usuarios, su naturaleza global de desarrollo, es presico un sistema de documentación integral. Previamente ya se ha considerado una discusión profunda sobre la necesidad de documentar DHIS2. Store2007 DocBook es un sistema exhaustivo basado en XML para crear libros, artículos y otros documentos técnicos bajo el soporte de OASIS .

Introducción - One of the main advantages of DocBook is that there is complete separation between the -content and presentation. DocBook is a pure XML format, and is well documented. It is believed that only a very small subset of its features will be required in order to achieve much higher quality documentation for DHIS. There are some 400 separate mark-up elements that cater to almost any level of technical documentation needs, but in reality, only a few dozen of these element will probably need to be employed to achieve high-quality documentation for DHIS 2, both for printed as well as on-line formats such as HTML or integrated help systems within the application itself. Therefore, there are wide range of possibilities in terms of which editor can be used for the creation of DocBook files. A fairly complete list of possibilities is located here. It is currently recommended to use Syntext Serna Free for editing DocBook source files as WYSIWYG. In principle, any text editing program or XML editor will be capable of being used to create DocBook files. + Una de las principales ventajas de DocBook es que hay una separación total entre el contenido y la presentación. DocBook es un formato puro XML, y está bastante documentado. En realidad con solo un pequeño conjunto de sus funcionalidades se podría lograr mucho mayor calidad de documentación para DHIS. Hay cerca de 400 elementos de marcado distintos que cubren prácticamente todos los niveles de necesidades en la documentación técnica, pero en realidad, con unas pocas docenas de estos elementos se puede lograr una buena calidad de documentación en DHIS2, tanto para formatos impresos como para formatos digitales como HTML o sistemas integrados de ayuda en la propia aplicación. Entonces, hay un amplio margen de posibilidades en términos de qué editor se puede usar para crear ficheros DocBook. Aquí hay una lista muy completa de posibilidades. Actualmente recomendamos utilizar Syntext Serna Free para editar los ficheros fuente de DocBook con un editor amigable WYSIWYG. En principio, cualquier programa de edición de texto o XML también es capaz de manejar y crear ficheros para DocBook. - It is not recommended to use the editor XMLmind XML Editor Personal Edition (also known as XXE Personal), as the editor "silently" places unneeded whitespace and other ornamentation to the DocBook source which makes collaborative editing of documents very difficult. + No recomendamos utilizar el editor XMLmind XML Editor Personal Edition (también conocido como XXE Personal), ya que el editor coloca "imperceptiblemente" espacios en blanco innecesarios y otros adornos en la fuente DocBook que dificultan la edición colaborativa de documentos. - One of the key concepts to keep in mind when authoring documentation in DocBook, or other -presentation neutral formats, is that the content of the document should be considered in the first instance. The presentation of the document will take place in a separate step, where it will be rendered into -different formats, such as HTML and PDF. It is therefore important that the document is will organised and structured, with appropriate DocBook tags and structural elements being considered. - It is good practise to break your document in to various sections using the -"sect", or section element. Section elements can also be nested within each other, such as "Section 1" and "Section 2". This concept is essentially the same as Microsoft Word or other word processing programs. DocBook will automatically take care of numbering the sections for you when the document is produced. Two other important elements are the "itemizedlist" and "numberedlist". These are quite similar, but an itemised list corresponds to a bulleted list, which a numbered list will be rendered with each element being numbered sequentially. Other key elements are "screenshot" and "table" which should be self-explanatory. + Uno de los conceptos clave a tener en mente al escribir documentación en DocBook, o en otros formatos neutrales de presentación, es que el contenido del documento debería ser lo prioritario. La presentación del documento se realizará en una fase separada, donde se renderiza a diferentes formatos como HTML o PDF. Por tanto, es importante que el documento esté organizado y estructurado, con las etiquetas apropiadas de DocBook y los elementos estructurales necesarios. + Es bueno practicar dividiendo el docmento en varias secciones utando el elemento "section". Los elementos de sección pueden anidarse, como "Sección 1" y "Sección 2". Este concepto es esencialmente el mismo que utilizan Microsoft Word u otros programas de procesado de textos. DocBook automáticamente anota los números de sección por nosotros al momento de generar el documento. Otros dos elementos importantes son las listas guionizadas ("itemizedlist") y las listas numeradas ("numberedlist"). Otros elementos clave son la captura de pantalla ("screenshot") y las tablas ("table").

Primeros pasos con Launchpad - Currently, the documentation system is part of the source code housed at Launchpad. Launchpad is a collaborative platform that enables multiple people to work on software projects collaboratively. In order for this to be possible, a version control system is necessary in order to manage all the changes that multiple users may make. Launchpad uses the Bazaar source control system. While it is beyond the scope of this document to describe the functionality of Bazaar, users who wish to create documentation will need to gain at -least a basic understanding of how the system works. A basic guide is provided in the next section. - In order to start adding or editing the documentation, you should first perform a -checkout of the source code. If you do not already have a Launchpad login id, you will need to get one. This can be done here. Once you register with Launchpad, you will need to request access to the dhis2-documenters group. Login to Launchpad, and then request access here. Your request will need to be approved by the group administrators. Once you have been granted access to the group, you can commit changes to the documentation branch and send and receive emails on the groups' list. + Actualmente el sistema de documentación es parte del código fuente alojado en Launchpad. Launchpad es una plataforma colaborativa que permite que muchas personas trabajen en proyectos software de forma colaborativa. Para que esto sea posible es necesario un sistema de control de versiones que maneje todos los cambios realizados por múltiples usuarios. Launchpad utiliza el sistema de control de fuentes llamado Bazaar. Aunque se sale del alcance de este documento describir las características de Bazaar, los usuarios que deseen crear documentación necesitarán al menos cierta comprensión de cómo funciona el sistema. En la siguiente sección se detalla una guía breve al respecto. + Para comenzar añadiendo o editando la documentación, lo primero es sincronizar el código fuente. Si no disponemos aún de un identificador para loguearnos en Launchpad, necesitaremos obtener uno. Esto podemos hacerlo aquí. Una vez nos hemos registrado en Launchpad, podemos solicitar acceso al archivo de documentadores de DHIS aquí. La solicitud deberá esperar a ser aprobada por el grupo de administradores. Cuando nos hayan concedido acceso al grupo, podemos subir los cambios al archivo de documentación y enviar y recibir emails de la lista de correo del grupo.

Obtención de la fuente de documentos - In order to edit the documentation, you will need to download the source pages of the -documentation to your computer. Launchpad uses a version control system known as bzr . There are different methods for getting Bazaar working on your system, depending on which operating system you are using. A good step-by-step guide for Microsoft operating systems can be viewed here. If you are using Linux, you will need to install bzr on your system through your package manager, or from source code. - Once you have installed bzr on your system, you will need to download the document source. -Just follow this procedure: + Para poder editar la documentación, necesitaremos descargar las páginas fuente de la documentación en nuestra computadora local. Launchpad utiliza un sistema de control de versiones conocido como bzr, Bazaar. Hay diferentes formas de instalar Bazaar en nuestro sistema, dependiendo del sistema operativo que estemos utilizando. Una buena guía por pasos para sistemas operativos Microsoft se puede encontrar aquí y para MacOSX aquí. Los usuarios de Linux podrán instalar bzr en su sistema mediante el gestor de instalación de paquetes, o desde el código fuente. + Cuando tenemos instalado bzr en el sistema, necesitaremos descargar la fuente de documentación. Simplemente seguiremos este procedimiento: - Make sure you have Bazaar installed. - - - Start Bazaar by right-clicking a folder if you are using Windows and selecting Bzr Here. If you use Linux, you can just create a folder to hold the document sources. You can place the document source in any folder you like. - - - To download the latest revision of the DHIS2 documents project type: bzr checkout lp:~dhis2-documenters/dhis2/dhis2-docbook-docs if you are using Linux, or alternatively if you are using Windows type the url to the source code repository "lp:~dhis2-documenters/dhis2/dhis2-docbook-docs" - - - The download process should start and all the documentation source files will be -downloaded to the folder that you specified. + Nos aseguraremos de que Bazaar está instalado. + + + Arrancamos Bazaar haciendo click con el botón derecho del ratón en una carpeta si estamos manejando Windows y seleccionamos Bzr aquí. Si usamos Linux, podemos simplemente crear una carpeta para que contenga los fuentes. Podemos colocar los fuentes de documentación en la carpeta que deseemos. + + + Para descargar la última revisión del proyecto de documentación de DHIS2 tipeamos en el terminal de comandos:bzr checkout lp:~dhis2-documenters/dhis2/dhis2-docbook-docs + desde Linux o MacOSX, o si usamos Windows escribiremos la URL del repositorio de código fuente "lp:~dhis2-documenters/dhis2/dhis2-docbook-docs" + + + El proceso de descarga debería empezar en este momento y se descargarán todos los ficheros fuente de la documentación a la carpeta especificada.

Editando la documentación - Once you have downloaded the source, you should have a series of folders inside of the -dhis2-docbook-docs directory. All documents should be placed in the dhis2-docbook-docs/src/docbkx/XX folder. Note that the XX represents the ISO 639-1 (two-letter) language code of the documentation. If you are developing English language documentation, place it inside the /dhis2-docbook-docs/src/docbkx/en/ folder. Place any image files that may be linked to your document in the /dhis2-docbook-docs/src/docbkx/XX/resources/images folder and link these inside your DocBook document using a relative file link. When the documentation is built, in a separate step, the images will be automatically copied over to the correct directory during the build process. + Cuando hayamos descargado los fuentes, deberemos tener un montón de carpetas dentro del directorio dhis2-docbook-docs. Todos los documentos fuente deberían estar ubicados en la carpetadhis2-docbook-docs/src/docbkx/XX. Notemos aquí que XX representa la pareja de letras de codificación de idioma ISO 639-1. Entonces, para elaborar la documentación en idioma inglés, nos ubicaremos en la carpeta /dhis2-docbook-docs/src/docbkx/en/, mientras que para elaborar la documentación en español trabajaremos siempre en la carpeta /dhis2-docbook-docs/src/docbkx/es/. Ubicaremos los ficheros imagen deseados para enlazarlos en nuestros documentos en la carpeta /dhis2-docbook-docs/src/docbkx/XX/resources/images y los enlazaremos desde el documento DocBoo utilizando un enlace relativo al fichero. Cuando la documentación ya se ha generado, en otra fase, las imágenes se copiarán al directorio correspondiente.

Bibliografía de DHIS2 - DHIS2 has a rich set of academic literature which can serve as invaluable resources during implementations, project proposals and more detailed reading than what is appropriate for a general user manual. A specialized bibliography has been added to the source code of the application. BibTeX is a specialized language which is widely used in the academic world to handle bibliographic databases. A large number of free and open source tools are capable of working with BibTeX. Currently, the recommended tool of choice for manipulating the DHIS2 bibliography is JabRef. - To get started with the bibliography, download a copy of JabRef and open the /src/bibliography/dhis2_bibliography.bib file. . Add some new references, then export the bibliography back to the /src/docbkx/en/dhis2_bibliography.xml file, using the DocBook 4.4 export format. The updated bibliography will automatically be included in the documentation after you commit your changes. + DHIS2 tiene un rico conjunto de literatura académica que puede servir como recursos de valor incalculable durante las implementaciones, propuestas de proyectos y como lectura más detallada que el manual de usuario. Hemos añadido una bibliografía especializada al código fuente de la aplicación. BibTeX es un lenguaje especializado y ampliamente usado en el mundo académico para manejar bases de datos bibliográficas. Gran número de herramientas libres y de código abierto son capaces de trabajar con Bibtex. Actualmente, recomendamos utilizar JabRef para manejar la bibliografía de DHIS2. + Para comenzar con la bibliografía, descargaremos una copia de JabRef y abriremos el fichero/src/bibliography/dhis2_bibliography.bib. Podemos añadir ahí las referencias nuevas, y exportamos de vuelta la bibliografía al fichero/src/docbkx/en/dhis2_bibliography.xml, utilizando el formato de exportación DocBook 4.4. La bibliografía actualizada será incluida automáticamente en la documentación tras subir ("commit") nuestros cambios.

Manejando imágenes - Screen shots are very useful for providing information to users on how particular actions -should be performed. DocBook has no intrinsic mechanisms to know exactly how an image should be rendered in the final document. Therefore, it is necessary to provide instructions through element attributes. The following XML code fragment demonstrates how an image can be specified to occupy 80% of the available page width. For screen shots in landscape format, this seems to be an appropriate amount. You may need to experiment a bit to obtain a proper width for your image. Alternatively, you can edit the resolution of the image itself, in order to obtain a proper size during rendering. + Las capturas de pantalla son imágenes muy útiles para dar instrucciones a los usuarios sobre cómo llevar a cabo acciones concretas. DocBook no tiene mecanismos intrínsecos para saber exactamente cómo se debe renderizar una imagen en el documento final. Por eso es necesario dar ese detalle mediante atributos de elementos. El fragmento de código XML muestra cómo podemos especificar que una imagen ocupe el 80% de la anchura de página. Para capturas de pantalla en formato horizontal, esta cantidad parece apropiada. Tal vez queramos experimentar un poco para obtener el ancho más adecuado para nuestras imágenes. Una alternativa es editar la resolución de la imagen, para obtener un tamaño adecuado al renderizar. <screenshot> <screeninfo>DHIS2 Login screen</screeninfo> <mediaobject> @@ -70,15 +60,12 @@ </imageobject> </mediaobject> </screenshot> - For other images, depending on their size, a different value may be necessary. If you do -not specify a width for you image, and its intrinsic size is larger than the available screen width, the image may overflow in certain document types with a fixed width, such as PDF. + Para otras imágenes pueden precisarse valores distintos dependiendo de su tamaño. Si no tenemos una anchura específica para las imágenes y el tamaño real es mayor que el ancho de pantalla, la imagen puede desbordar algunos tipos de documento con anchura fija, como los PDF.

Cómo enlazar documentos - DocBook provides a modular framework where many separate documents can be linked together -into a master document. Fragments from different documents can also be reused in different contexts. It is therefore important to consider whether your document should be constructed as an article or a chapter. Chapters are essentially portions of a book, and can therefore be linked together into a larger document very easily. Articles are essentially standalone documents, but they can also be assembled together into a larger document at the component level. - 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. + DocBook tiene un entorno modular donde es posible enlazar muchos documentos distintos en un mismo documento master. Los fragmentos de esos documentos deberían montare en forma de artículo o capítulo. Los capítulos son partes esenciales de un libro, de modo que se pueden enlazar de nuevo en un documento mayor con facilidad. Los artículos son generalmente documentos independientes, pero también pueden combinarse en un documento mayor que los contenga. + Si queremos enlazar muchos artículos en un libro, DocBook ofrece un mecanismo para asignar un identificador a cada sección. En el ejemplo siguiente, cada sección tiene asignado un identificador ("id"). Este identificador debe ser único en todo el documento. <section id="mod2_1"> <title>Getting started with DHIS2</title> .... @@ -91,43 +78,35 @@ xpointer="mod2_1" encoding="UTF-8"/> ... - Note that the file name and id have been assigned in the parent document, referring to the -actual file (href) and particular fragment of the child document that should be referenced in the parent document (xpointer). - Including chapters in a book is very simple. The example below illustrates how: + Notemos que el nombre del dichero y el identificador se asignan en el documento padre, con referencia al fichero actual (href) y a un fragmento concreto del documento hijo que debería referenciarse en el documento padre (xpointer). + Es sencillo incluir capítulos en un libro. Este ejemplo muestra cómo hacerlo: <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_ mod1.xml" encoding="UTF-8"/> - In this case, there is no need to explicitly reference a part of the document, unless you -only want to include a portion of the chapter. If you want to use a section of the chapter, you can assign an id to that section, and then reference that section through an xpointer. + En este caso no hay necesidad de referenciar explícitamente una parte del documento, a menos que solo queramos incluir una parte del capítulo. Si queremos utilizar una sección del capítulo, podemos asignar un "id" a esa sección, y luego referenciarla mediante un "xpointer".

Manejando documentación en varios idiomas - The directory structure of the documentation has been created in order to facilitate the -creation of documents in any language. If you want to create a new set of documents in a given language, simply create a new directory in the dhis2-docbook-docs/src/docbkx/ directory. Be sure to use the ISO 639-1 code for the language you are going to create documents in. A complete list of these codes can be found here. Add a new folder for -images in a sub-directory , replacing XX with the actual ISO 639-1 code for the language you will create documents in. You will also need to edit the pom.xml file in the main dhis2-docbook-docs directory. If you are unsure of what changes need to be made to this file, ask on the mailing list first, as this file controls the generation of all the documentation. + La estructura del directorio de documentación ha sido creada para facilitar la generación de documentos en cualquier idioma. Si queremos crear un nuevo conjunto de documentos en un determinado idioma, simplemente crearemos un nuevo directorio en la carpeta dhis2-docbook-docs/src/docbkx/ y lo llamaremos "XX" reemplazando las x por el código de idioma. Deberemos asegurarnos de utilizar un código ISO 639-1 para el idioma en el que escribiremos los documentos. Hay una lista completa de estos códigos aquí. Añadiremos una nueva subcarpeta para las imágenes. Deberemos también generar una copia del fichero pom.xml en el directorio dhis2-docbook-docs, y lo nombraremos XX-pom.xml y adaptaremos a nuestro árbol nuevo de directorios (ver los ficheros pom.xml y es-pom.xml como ejemplo). Si no estás seguro de cómo hacer los cambios necesarios en este fichero, pregunta en la lista de correo primero, ya que estos ficheros pom controlan la generación de toda la documentación.

- Cómo compilar la documentación - One of the key advantages of the DocBook format is that the source documentation can be -transformed into a wide variety of formats, including HTML, chunked HTML, XHTML, PDF, and a number of other formats. There are a wide variety of tools that are capable of performing this task. Basically the XML source of the document is transformed using the standard DocBook XSL style sheets into the desired format. The complete list of tools capable of transforming DocBook will not be listed here, but a few examples are provided below. - Latest builds of the documentation are available from the DHIS2 website. The latest snapshot builds are available through the continuous integration server located here. + Cómo generar la documentación + Una de las ventajas cruciales del formato DocBook es que la documentación fuente puede transformarse en gran variedad de formatos como HTML, HTML truncado, XHTML, PDF, y muchos otros. Hay variedad de herramientas capaces de realizar esta transformación. Básicamente las páginas XML fuente se transforman utilizando las páginas de estilo XSL de DocBook en el formato deseado. No hemos incluido aquí la lista completa de herramientas capaces de transformar DocBook, pero a continuación damos algunos ejemplos. + Las últimas generaciones de documentación están disponibles en el sitio web de DHIS2. La últimas versiones están disponibles mediante el servidor de integración continua ubicado aquí.

- Compilar la documentación con Apache maven - In order to transform the documentation source files to different formats, such as HTML -or PDF, you will need to install the Apache Maven program. You can get a copy here or by installing it through your package manager if you are using Linux. Just execute the command mvn clean package on Windows or on Linux from the /dhis2-docbook-docs directory. Maven will start to download the necessary components to transform the -documents into HMTL,PDF and RTF. Once the process has completed (be patient the first time, as there are a number of components that must be downloaded), all of the target document types will be generated in the /dhis2-docbook-docs/target/docbkx directory in respective sub-directories. + Generar la documentación con Apache maven + Para transformar los ficheros de documentación fuente en distintos formatos, como HTML y PDF, necesitaremos instalar el programa de Apache Maven. Podremos obtener una copia aquí o instalándolo mediante el gestor de paquetes en Linux. En el terminal ejecutaremos el comando mvn clean package en Windows, MacOSX o Linux desde el directorio /dhis2-docbook-docs . Maven comenzará a descargar los componentes necesarios para convertir los documentos en HTML, PDF y RTF. Cuando el proceso haya terminado (hemos de ser pacientes la primera vez, ya que hay muchos componentes que descargar), podremos generar todo tipo de documentos en el directorio dhis2-docbook-docs/target/docbkx y los subdirectorios correspondientes.

- Compilar con xmlto - xmlto is a useful utility available on Linux platforms for -transforming DocBook documents into many different formats. More information on the package can be found here. If you do not want to use Apache Maven for some reason, you can install xmlto through your package manager. Once you have installed xmlto you can just execute xmlto htmlfile_to_transform where the file_to_transform parameter is the name of the file you wish to transform. There are many other formats available, such as PDF, PS, JavaHelp and others. + Generar la documentación con xmlto + xmlto es una utilidad disponible en plataformas Linux para convertir documentos de DocBook en diversos formatos. Es posible encontrar más información sobre este paquete aquí. Si por alguna razón no queremos utilizar Apache Maven, podremos instalar xmlto mediante el gestor de paquetes. Después de instalar xmlto bastará con ejecutar xmlto htmlfile_to_transform donde el parámetro file_to_transform es el nombre del fichero que deseamos convertir. Hay otros formatos disponibles como PDF, PS, Java Help y otros.

Cómo subir los cambios a Launchpad - Once you have finished editing your document, you will need to commit your changes back to -Launchpad. Open up a command prompt on Windows or a shell on Linux, and navigate to the folder where you have placed your documentation. If you have added any new files or folders to your local repository, you will need to add them to the source tree with the bzr add command, followed by the folder or file name(s) that you have added Once you have added all of your new files, you should update you local repository to make sure there are no conflicts using the following command bzr update - If there are conflicts, bazaar will notify you of this. Your conflicts can also be listed by using the bzr conflicts command. If there are conflicts in a file, bazaar will create three versions of the file: + Una vez hemos terminado de editar los documentos, deberemos subir los cambios a Launchpad mediante la acción "commit". Abrimos un terminal y navegamos a la carpeta donde tenemos la documentación. Si hemos añadido nuevos ficheros o carpetas en el repositorio local, necesitaremos añadirlos al árbol de fuente con el comando bzr add seguido de la ruta al fichero o carpeta añadido. Después de añadir todos los ficheros, deberemos actualizar el repositorio local para asegurarnos de que no hay conflictos utilizando en comando bzr update + Si hay conflictos, Bazaar nos notificará esto. Los conflictos se pueden listar usando el comando bzr conflicts. Si hay conflictos en un fichero, Bazaar creará tres versiones de ese fichero + : filename.BASE @@ -139,15 +118,14 @@ filename.OTHER - These files correspond to the common parts of the file, the local version and the version on the server respectively. The files will contain markers to indicate areas in conflict. After resolving the conflicts by editing each file and removing the conflict markers, use bzr resolve. This will tell bazaar that the conflict is resolved, and clean up the BASE, THIS, OTHER files. - Once your source code is updated and any conflicts resolved, commit you changes with an informative message about the changes you have made: + Estos ficheros corresponden a partes comunes del fichero, a la versión local y a la versión del servidor respectivamente. Los ficheros contendrán marcadores para indicar las áreas en conflicto. Después de resolver los conflictos editando cada fichero y eliminando los marcadores de conflicto, utilizaremos el comando bzr resolve. Esto indica a Bazaar que el conflicto ha sido resuelto, y eliminará los ficheros BASE, THIS, OTHER. + Cuando nuestro código fuente está actualizado y se han resuelto los conflictos que hubiese, podemos subir los cambios incluyendo un mensaje informativo acerca de los cambios realizados:

- bzr commit -m "Created Amharic translation of documentation" + bzr commit -m "Created Aymara translation of documentation"

- Never commit code using bzr push, as this will overwrite any changes in the repository, and revision history will be lost. + No debemos nunca subir el código utilizando el comando bzr push, que sobreescribe todos los cambios en el repositorio, y el historial de revisión se perdería. - If you have any questions, or cannot find that you can get started, just send an email -with your problem to dhis2-documenters@lists.launchpad.net. + Si tienes alguna duda sobre cómo utilizar la documentación, o no consigues saber cómo empezar, envía un email con tus preguntas a dhis2-documenters@lists.launchpad.net.