En Zendesk, toda la documentación al alcance del público se publica en este centro de ayuda de Zendesk. A pesar de que la mayoría de los otros equipos de Zendesk crean contenido directamente en el centro de ayuda, el equipo de documentación crea y mantiene desconectada la documentación de los productos en archivos fuente en DITA. DITA (Darwin Information Typing Architecture) es un modelo de datos basado en XML para la autoría y publicación de contenido. En esencia, los archivos DITA son archivos XML de texto sin formato.
En este artículo se tratan los siguientes temas:
Por qué se usa DITA
DITA es una norma de la industria para crear y mantener grandes conjuntos de documentación. Se diseñó para publicar contenido en varios canales a partir de una sola fuente. En techwhirl.com, Jacquie Samuels describe así el problema que trata de solucionar:
Escribir contenido en Word, correo electrónico, PowerPoint, WordPress, HTML, InDesign, FrameMaker u otro formato es como escribir en tabletas de piedra. El contenido queda básicamente fijo en ese formato sin poderse modificar; no se puede reutilizar ni reaplicar, y es ineficiente y costoso.
DITA es una manera de escribir y almacenar el contenido para poderlo manejar como un recurso. Aprovecha el XML (eXtensible Markup Language) para hacer que el contenido sea inteligente, versátil, manejable y portátil.
Por ejemplo, el contenido que se crea en DITA se puede publicar (con una marca) en formato PDF, HTML, RTF, PowerPoint y en móviles, sin necesidad de copiar y pegar nada entre archivos.
(Fuente: ¿Qué es DITA? en TechWhirl)
Además de separar el contenido del formato, estas son otras ventajas de DITA para el equipo de documentación de Zendesk:
- Nos hace disciplinados en lo que se refiere a la estructura del contenido. Un archivo de DITA es XML. Si la estructura no es válida, la herramienta no nos deja hacer nada con esta.
- Nos permite mover el contenido con facilidad. Solo es necesario arrastrar el nodo del tema de un lugar a otro de la estructura.
- Nos permite reutilizar el contenido importando secciones de este en varios artículos.
- No publicamos archivos en formato PDF a menudo, pero, cuando lo hacemos, usamos archivos fuente en DITA.
La herramienta de autoría de DITA que usamos es Oxygen XML Author. A la solidez del entorno de autoría se suman también muchas otras funciones, como la búsqueda, la validación y las transformaciones de XHTML. Algunas de las herramientas de autoría de DITA son Framemaker, Arbortext y XMetal.
Cómo escribimos y publicamos artículos
Los escritores utilizan Oxygen XML Author para crear o actualizar el contenido en los archivos DITA. Como DITA se creó para permitir la publicación en varios canales desde una sola fuente, los archivos de texto DITA no contienen ningún estilo. Lo único que tienen es contenido estructurado. Para el canal web, el estilo lo proporcionan las hojas de estilo CSS externas, no DITA. En nuestro caso, el estilo se toma de las hojas de estilo de nuestro tema de Guide.
Cuando estamos listos para publicar (normalmente cuando se introduce o se actualiza una función del producto), usamos Author para transformar el DITA a XHTML, que es una versión más estricta de HTML. Luego publicamos el XHTML en el centro de ayuda usando la API del centro de ayuda.
A partir de la versión 24, Oxygen XML Editor incluye un escenario de transformación incorporado que puede publicar temas de DITA en salida de XHTML y cargarlos directamente como artículos en un centro de ayuda de Zendesk. Consulte DITA Map Publishing en la ayuda del XML Editor. Si desea ver un video, consulte Publishing Content to Zendesk Help Center en la ayuda del XML Editor.
En ocasiones, necesitamos actualizar muchos artículo en poco tiempo. Por ejemplo, cuando Zendesk simplificó sus precios y marcas, fue necesario publicar cientos de artículos modificados a más tardar a las 8 a.m. hora del Pacífico en una fecha específica. En las semanas anteriores al cambio, los escritores actualizaron los archivos fuente en DITA, y luego usamos Author para hacer una transformación por lotes de los archivos. Posteriormente, los enviamos al centro de ayuda usando la API del centro de ayuda. La publicación de estos tardó solo algunos minutos.
Cómo administramos los archivos
Usamos GitHub para administrar nuestros archivos DITA. Antes de crear o actualizar un artículo, un escritor crea una rama en nuestro repositorio, hace los cambios y luego crea una solicitud pull. Los demás escritores del equipo revisan la solicitud pull, lo que tiene la ventaja adicional de permitir que unos revisen el trabajo de otros.
Almacenamos las imágenes en Amazon S3 (Amazon Simple Storage Service), un servicio escalable de almacenamiento en la nube proporcionado por Amazon Web Services (AWS). Todas las imágenes de nuestros artículos se envían al navegador desde S3, no desde el centro de ayuda. El servicio Amazon S3 hace más sencillo el manejo de las imágenes.
Cómo publicamos los artículos traducidos
El idioma predeterminado de nuestros centros de ayuda es el inglés. También publicamos la documentación de los productos en alemán, español, francés, japonés, coreano, portugués de Brasil, italiano y chino simplificado.
Cuando hay que hacer una transferencia de los archivos para traducción, usamos la API del centro de ayuda para descargar archivos seleccionados en inglés del centro de ayuda y escribirlos como archivos HTML. Usamos la API de Amazon AWS para descargar las imágenes de los artículos de nuestro depósito en Amazon S3. Agrupamos las imágenes y los archivos HTML y se lo enviamos todo a nuestro proveedor de traducciones. Cuando recibimos las traducciones del proveedor, cargamos los artículos y las imágenes con la API del centro de ayuda y la API de AWS.