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 (Document Information Typing Architecture) es un modelo de datos basado en XML para la autoría y publicación de contenido.
En este artículo se tratan los siguientes temas:
Por qué se usa DITA
Data es una norma de la industria para crear y mantener grandes conjuntos de documentación. 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. Además de un entorno de autoría sólido, confiamos en muchas otras funciones, entre otras, búsqueda de archivos, diferencias de archivos, seguimiento de cambios y transformaciones de HTML. Algunas de las herramientas de autoría de DITA son Framemaker, Arbortext y XMetal.
Cómo publicamos en el centro de ayuda
Para crear o actualizar contenido en los archivos fuente en DITA, usamos Author. Cuando estamos listos para publicar, (por lo general, al mismo tiempo que se introduce o se actualiza una función de un producto), transformamos el contenido de DITA en HTML, luego pegamos manualmente el HTML fuente en el editor de código de Guide. La sencillez de este proceso compensa su falta de elegancia.
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, luego se hizo una transformación por lotes de los archivos y se enviaron al centro de ayuda usando la API de Zendesk. La publicación de estos tardó solo algunos minutos.
La herramienta de publicación en lote que usamos es de código abierto en Github, y todos pueden usarla. Consulte https://github.com/chucknado/zpu. Para obtener las instrucciones de uso, consulte el archivo léame en https://github.com/chucknado/zpu/blob/master/README.md.
Cómo administramos los archivos
Los archivos de DITA se almacenan en un Team Drive de Google, que los sincroniza automáticamente con la computadora de cada escritor. Así, el escritor tiene siempre a la mano las versiones más recientes. Cuando un escritor guarda cambios en un artículo, estos se propagan de inmediato a las computadoras de los demás escritores a través de la sincronización de Team Drive. Team Drive también conserva los cambios de los últimos 30 días. Como indicamos, el objetivo es que el proceso sea sencillo.
También almacenamos imágenes en el Team Drive de Google, pero las cargamos en un servidor de archivos de Amazon S3 para ponerlas a disposición del publico. Todas las imágenes de nuestros artículos se descargan en el navegador desde el 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 y portugués de Brasil.
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 de los centros de ayuda y escribirlos como archivos HTML. Usamos la API de Amazon para descargar las imágenes de los artículos de nuestro depósito en Amazon S3. Agrupamos los archivos y los enviamos a nuestro proveedor de traducciones. Cuando recibimos las traducciones del proveedor, cargamos los artículos y las imágenes con las API del centro de ayuda y de Amazon.
El cliente API que usamos para manejar los archivos de transferencia se llama ZLO (Zendesk localization tools), y fue creado internamente por el equipo de documentación. El cliente ZLO es de código abierto y está disponible en Github en https://github.com/chucknado/zlo. En la documentación de Github, puede leer más información sobre esto.