Guía de documentación migasfree

Transcripción

1 1. Introducción Guía de documentación migasfree Alberto Gacías migasfree.org En este artículo se describe lo que debes tener en cuenta para generar documentación en migasfree. 2. Formato fuente de los documentos Según el proyecto GNOME, para la creación de artículos, libros, tutoriales, etc. se hace necesario utilizar un medio de documentación estándar de manera que tanto la modificación de los documentos fuentes como la generación de estos en diferentes formatos sea sencilla. DocBook es un lenguaje para escribir documentos estructurados usando XML. Es muy utilizado en la comunidad de software libre dónde destaca Linux Documentation Project, las referencias de las APIs de GNOME y GTK+, así como la documentación del núcleo y de las Distribuciones Linux más conocidas. Puedes escribir y modificar documentos DocBook con cualquier editor de texto, pero te resultará mucho más sencillo si usas un editor XML, como por ejemplo XMLmind Editor ("XXE"). 3. Instalación y configuración de XMLmind Editor (XXE) 1. Instala XMLmind Editor (XXE). Descarga y descomprimelo. 1

2 Ejecuta bin/xxe A continuación accede al menú Options-Install Add-ons y selecciona: "Spanish (español) translations" para que el Interfaz Gráfico de Usuario aparezca en español. "Spanish (español) Dictionary" para hacer las correcciones ortográficas. Reinicia XXE. A continuación ve a Opciones - Preferencias y en "Guardar" elige codificación UTF Instala el paquete docbook-utils: zypper install docbook-utils 4. Primeros pasos con XXE Desde XXE hacemos Archivo-Nuevo. Elegimos Docbook-Artículo. Inserta el título del artículo, tu nombre y apellidos, el nombre de la organización (migasfree.org) y la fecha actual. Fíjate en la barra de nodos para saber dónde está cada uno de ellos. A continuación escribiremos algo de contenido. Sitúa el cursor a la derecha del "1" y escribe el título de la sección. Tabula para empezar a escribir un párrafo. Pulsa Enter para añadir otro parrafo. 2

3 Una de las ventajas de DocBook es que se pueden establecer metadatos (datos sobre los datos). Simplemente selecciona la palabra o palabras que quieras definir, pulsa Ctrl+T (Convert) y a continuación elige del panel de la derecha (Editar), el metadato adecuado. Cada tipo de metadato aparecerá con un formato diferente. Table 1. Metadatos Convert (Ctrl+T) Ejemplo nombre de fichero filename /etc/migas.conf comando command ssh url ulink (en atributos se especifica la url) paquete package apache2 listado de programa programlisting cd /home dir Ahora añade una sección. Para ello sitúate en cualquier parte de un párrafo y selecciona en la barra de nodos "article-seccion" pulsando en "section". A continuacion haz Editar-Insertar Despues (ó Ctrl+J). El cursor se habrá despalzado al panel Editar. Escribe section y pulsa Enter. Añade ahora una imágen. Sitúa el cursor en el lugar del documento en donde quieres poner la imagen. Pulsa Ctrl+J y elige mediaobject. Haz doble click en el icono que aparezca y elige la imagen. Si la imagen es grande, en el panel Atributos (a la derecha debajo del panel Editar) especifica la escala de la imagen, por ejemplo scale 50. Note: Puedes leer [Getting Started with XMLming XML editor] en la ayuda de XXE para familiarizarte con la aplicación. 5. Recomendaciones para la escritura. Una buena documentación técnica se caracteriza porque es: Comprensiva. Describe todas las funcionalidades del producto. No omitas funcionalidades que consideras irrelevantes para el usuario. Conforme. Describe la realidad, no lo que deseas transmitir. Presenta la información en el orden en que los usuarios experimentan la materia. 3

4 Clara. Que tu texto no genere dudas en el lector con rodeos o redundancias. Víctor Hurtado dice Escribir con claridad significa ser entendido a la primera lectura. Concisa. Revisa tu trabajo con frecuencia a medida que escribes tu documento. Existen unas reglas de oro para que la documentación sea sencilla y fácil de leer. Regla de oro 1. Limita cada frase a menos de 25 palabras: Example 1. Sé conciso. "Bajo condiciones normales, el kernel no siempre escribe los datos a disco inmediatamente, si no que los guarda en un buffer de memoria para periódicamente escribirlos a disco y así agilizar las operaciones." "Generalmente, el kernel almacena el dato en memoria antes de escribirlo periódicamente a disco." Pregúntate que palabras puedes eliminar y elimínalas. "Usa el comando ssh para..." "Usa ssh para.." Regla de oro 2. Cada párrafo es un tema. Cada frase una idea. Consejo: Planifica el orden de los párrafos antes de empezar a escribir. Decide de qué tema quieres hablar en cada párrafo Regla de oro 3. Usa ejemplos explícitos para demostrar cómo funciona una aplicación. Proporciona instrucciones en vez de descripciones. Example 2. Proporciona instrucciones "Hay una caja de texto que se puede usar para buscar la definición de una palabra." "Para buscar la definición de una palabra, escríbala en la caja de texto y pulse el botón Buscar." 4

5 Regla de oro 4. Escribe de un modo neutral. Example 3. Sé neutral "La aplicación es un pequeño capturador de pantallas" "Puede usar la aplicación para hacer una captura de pantalla." 6. Generando la documentación a partir del XML Antes de grabar debemos verificar la validez del documento XML con Herramientas-Verificar validez, y verificar la ortografía mediante Herramientas-Verificar ortografía. Una vez grabado el fichero fuente DocBook con Archivo-Guardar, podemos utilizar db2pdf desde un terminal para generar el fichero pdf, y db2html para generar el documento en html. db2pdf miarticulo.xml db2html miarticulo.xml 7. Ubicación de los archivos Los archivos fuentes XML se ubicarán en la carpeta doc del proyecto ubicado en git@github.com:agacias/migasfree.git Las imágenes se ubicarán en la carpeta doc/media/images Los archivos html y pdf generados serán almacenados en migasfree.org 5

6 8. Enlaces