Para publicar grandes proyectos de documentación, DocBook es el marco ideal. Consiste en un idioma (DocBook XML) y un conjunto de hojas de estilo para traducir este idioma a diferentes formatos de salida como HTML, PDF y EPUB.

Las hojas de estilo definen el diseño que desea aplicar al transformar las fuentes XML en formatos de salida. Para la documentación de SUSE, escribimos nuestras propias hojas de estilo XSLT para garantizar que el diseño corporativo se refleje correctamente.

El lenguaje DocBook XML se basa en el eXtensible Markup Language (XML) y define el contenido de forma semántica a través de elementos como HTML. DocBook en sí está escrito como un esquema que define los nombres de los elementos y el contenido y dónde pueden aparecer. El esquema DocBook se utiliza para realizar dos tareas: edición guiada y validación.

La edición guiada se realiza a través de un editor XML (como oXygen, Vim o Emacs). El editor lee el esquema de DocBook y sugiere qué elementos están permitidos en el contexto actual. La validación da pistas sobre errores estructurales en un documento XML; esto podría, por ejemplo, ser un elemento faltante.

Los productos similares a menudo comparten una cantidad considerable de características y solo difieren en los detalles. Si desea generar múltiples variantes de documentación a partir de sus archivos XML, puede hacerlo con la ayuda de texto condicional, o creación de perfiles, como se llama en DocBook. Por ejemplo, puede perfilar ciertas partes de sus textos XML para diferentes arquitecturas (procesadores), sistemas operativos, proveedores o grupos objetivo.

Si bien aprender DocBook puede parecer engorroso a primera vista, tiene muchas ventajas únicas. Entre otros, es ideal para las estructuras modulares de documentación compleja, proporciona perfiles y puede generar muchos formatos de salida diferentes a partir de las mismas fuentes XML.

AsciiDoc: una alternativa para una contribución sencilla

Los proyectos de documentación son cada vez más complejos y dependen cada vez más de las contribuciones de expertos externos, que no tienen experiencia en redacción técnica. Para esos proyectos y colaboradores, AsciiDoc ofrece una alternativa seria. AsciiDoc pertenece a los lenguajes de marcado ligeros y proporciona una sintaxis y un procesador de documentación de texto sin formato. No es tan modular y extenso como DocBook, pero es fácil de entender y usar.

Una de las mayores ventajas de usar AsciiDoc como fuente de documentación es su perfecta integración con GitHub. GitHub no solo procesa fuentes AsciiDoc, sino que también permite editarlas directamente en la interfaz web. Esto encaja muy bien con el flujo de trabajo de solicitud de extracción basado en web de GitHub: edita el documento en línea, hace clic en un botón y alguien más (generalmente el propietario del repositorio) puede revisar e integrar el cambio. Todo lo que necesita es una cuenta de GitHub gratuita (que ya tienen muchos desarrolladores y expertos técnicos). Esto mejora el flujo de contribución para los contribuyentes externos.

Resumen

Cada formato de documento tiene algunas ventajas y desventajas. Por ejemplo, las tablas son complejas de crear con DocBook XML, pero lo mismo se aplica a las listas anidadas en AsciiDoc (tor). Somos flexibles, por lo tanto, nuestra cadena de herramientas es compatible con DocBook y AsciiDoc. Pero, por supuesto, no esperamos que los colaboradores proporcionen al equipo de documentación tablas XML complejas o similares. Cada colaborador es libre de escribir sus documentos con la herramienta de su elección, y el equipo de documentación los convierte en consecuencia.

Descargo de responsabilidad:  el texto en cuestión no ha sido revisado por un hablante nativo. Si encuentra errores tipográficos o de idioma, por favor envíelos a mí (meike.chabowski@suse.com).