Buenas tardes
Como uno de los desarrolladores del proyecto
Embox de código
abierto , a menudo escuché (muy a menudo últimamente) que el proyecto es interesante, pero como no hay documentación, no se puede usar. Respondimos que había algún tipo de documentación, que siempre podemos responder preguntas, que en casos extremos, puedes tratar de resolverlo por tu cuenta, porque el proyecto está abierto, pero todo esto no encajaba. Tuve que lidiar con este tema muy desagradable para los desarrolladores. ¡Pero, naturalmente, el artículo no trata sobre el hecho de que la documentación es "desagradable"! Y sobre cómo hicimos el proceso de desarrollo de documentación más cómodo. De hecho, en cualquier proyecto más o menos grande, surgen necesariamente problemas relacionados con la documentación.
Para aquellos que son demasiado flojos para leer, diré de inmediato que al final llegamos al desarrollo de la documentación en formato de descuento. Bueno, para aquellos que estén interesados en los detalles, las razones por las que se rebajan y cuáles son los pros y los contras de este enfoque, pido un gato.
Comenzaré justificando la relevancia del tema. No solo Embox tiene problemas de documentación. Por ejemplo, Google ha anunciado un análogo del programa Google Summer Of Code (GSOC) para escritores técnicos
Season of Docs . La empresa Kaspersky Lab celebra
conferencias para escritores técnicos . Y la compañía Parallels publica
artículos en el centro sobre cómo escribir documentación . Todo esto indica que el tema es importante y tal vez sin atención merecida.
La serie de artículos mencionados anteriormente comprende el contenido correcto de la documentación, pero quiero centrarme en el proceso de desarrollo de documentación, tecnología, si lo desea. De hecho, para un proyecto de código abierto, el sello distintivo es la apertura como una propiedad del proceso de desarrollo. Y queríamos crear un proceso que satisficiera los requisitos de nuestro proyecto.
Una breve digresión en la historia de nuestros procesos de desarrollo de documentación.
Una vez que el proyecto se ubicó en
googlecode . Teníamos un wiki bastante decente, muchos incluso lo recuerdan, preguntan dónde encontrarlo y piden transferirlo a github, donde se encuentra el proyecto ahora (o en otro lugar accesible). El wiki de googlecode fue realmente útil. Era multilingüe y, en mi opinión, tenía más funciones que el wiki en github. Pero sucedió que, junto con el propio googlecode, se ha hundido en el olvido. El wiki actual en github realiza bastante bien la función que se le asigna de entregar información operativa sobre el proyecto, pero es bastante difícil crear documentación completa en esta plataforma.
Por supuesto, para cualquier proyecto de código abierto, necesita documentación en línea (de acceso rápido) en línea, cuyo papel desempeña el wiki, y documentación completa disponible sin conexión, porque es mucho más fácil entender la esencia y la ideología del proyecto. Además, hacer búsquedas fuera de línea en un solo documento, en lugar de páginas wiki dispares, también es mucho más fácil.
Probablemente la mejor opción que conozco es la
documentación de ARM . Es decir, documentación en línea, donde hay una búsqueda en todas las secciones, pero hay un documento específico disponible para descargar en formato pdf. Desafortunadamente, Embox aún no ha alcanzado el nivel de ARM en términos de capacidades. Por lo tanto, tuvimos que hacer la versión fuera de línea por separado. Para esto, utilizamos el servicio
Google Docs . Es conveniente porque: le permite descargar datos en varios formatos, colaborar y tiene un sistema de control de versiones incorporado. Transferimos parte de la información del wiki, establecimos la estructura, porque el objetivo de desarrollar la versión fuera de línea era crear documentación holística y comenzamos a desarrollar varios documentos. Pero lo suficientemente rápido, nos encontramos con problemas. La información estaba desactualizada, los datos del wiki no coincidían con los datos de la documentación fuera de línea, y lo más importante, no pudimos crear la documentación completa. Había una estructura, pero como no era posible obtener comentarios decentes de los usuarios, resultó que solo sus creadores podían entender la documentación. Esto ciertamente no es un problema de servicio, pero el hecho, como dicen, es obvio. Tuvimos que buscar un enfoque diferente para este problema.
Luego tratamos de transferir los datos de la antigua wiki al wiki github, pero incluso entonces nos encontramos rápidamente con problemas. Descubrimos que parte de la información está desactualizada, parte no se ha agregado, parte no estaba claro cómo presentarla de forma fácil de usar. Continuando la búsqueda de una solución al problema, en algún momento, incluso consideramos desarrollar documentación en TeX usando el repositorio git, pero rápidamente nos dimos cuenta de que esto ya era demasiado. Aunque esta idea tuvo un impacto.
Decidimos formular lo que queremos de la documentación, es decir, del proceso de desarrollo de documentación, dejamos los contenidos fuera de los corchetes:
- La documentación debe mantenerse en formato de texto ya que se suponía que debía usar git como sistema de control de versiones.
- La documentación debe tener versiones en línea (wiki) y fuera de línea (documentos separados, por ejemplo, en pdf)
- La documentación en línea y fuera de línea debe poder sincronizarse fácilmente.
- La documentación debe constar de secciones (capítulos) que se pueden desarrollar o estudiar por separado, pero a partir de las cuales puede componer documentación completa
Ninguno de los puntos contradice el uso de markdown, y fue interesante ya que ya se usa en la wiki. Por supuesto, podría usar un formato diferente y convertirlo a Markdown. Pero después de compilar otra lista de requisitos, esta vez con la capacidad de agregar varios tipos de contenido (imágenes, texto, formato), llegamos a la conclusión de que el descuento satisface suficientemente todas nuestras necesidades actuales. Y el primer google sobre el tema "markdown to pdf" mostró que las opciones para convertir markdown a otros formatos existen y son bastante populares.
Hay varias opciones para convertir Markdown en PDF , pero
Pandoc es, con
mucho, el más popular. Esta utilidad puede convertir cualquier formato de texto en cualquier formato de texto. Además, está en voladizo. Por lo tanto, no solo nos es familiar, sino que también puede integrarse en scripts para crear documentación en varios formatos.
Decidimos sobre la utilidad y comenzamos a pensar en la siguiente pequeña pregunta que teníamos que resolver, a saber, cómo hacer un solo documento, y no muchos archivos pdf con capítulos diferentes obtenidos de archivos de descuento por separado. El primer deseo era simplemente "guardar" los archivos (para combinar texto de varios archivos) en la secuencia deseada, pero resultó ser mucho más simple, Pandoc en sí mismo es perfectamente capaz de trabajar con la lista de archivos. Esto también nos permitió resolver parcialmente el problema de que necesitamos varios documentos en los que el contenido puede cruzarse. Por ejemplo, generamos tres documentos y los tres contienen una breve descripción. Simplemente enumeramos este archivo en la lista de pandoc para todos los documentos.
Aplicamos un principio similar a las páginas de portada donde está contenido el título del documento, y así sucesivamente. Acabamos de crear archivos con encabezados para cada documento y los incluimos como los primeros archivos en la lista fuente de pandoc.
Como probablemente haya adivinado, esto (una lista de diferentes archivos) resuelve el problema con el multilingüismo, solo especificamos los archivos con el idioma deseado.
Hablemos un poco más sobre el ruso. Al generar pdf, pandoc usa latex como back-end para renderizar, corrector ortográfico, etc. De forma predeterminada, no se muestra cirílico y se muestra un error sobre un personaje desconocido. Esto se resuelve de manera muy simple, solo especifique "babel ruso".
--- ... header-includes: - \usepackage[russian]{babel} ---
Cabe señalar que es más correcto indicar
--- ... header-includes: - \usepackage[russian, english]{babel} ---
Y usa comandos de latex en el texto
\selectlanguage{russian} \foreignlanguage{english}{ English text }
O
\begin{otherlanguage}{english} Text in english \end{otherlanguage}
Pero dado que queríamos mantener una rebaja "limpia" para una posible transferencia a la wiki, y resultó que la directiva babel era suficiente para nuestros propósitos, decidimos no complicarla y la dejamos como está.
Por supuesto, queríamos no tener documentos formateados de ninguna manera, sino al menos tener un aspecto uniforme. Y aquí el látex nos ayudó de nuevo. El hecho es que dado que pandoc usa latex, puede especificarle plantillas de latex. Esto se hace simplemente con la opción --template
pandoc --template=embox_pandoc.latex ...
Después de compilar una plantilla y especificarla al generar todos los documentos, obtiene documentos en un estilo más o menos uniforme. "Más o menos", porque hay varios problemas que no hemos podido resolver. Por ejemplo, la formación de un solo bloque de código. En Markdown, es posible especificar un solo bloque de código para que no esté formateado y el resaltado de sintaxis esté posiblemente activado. Pero logramos hacer solo bloques de una línea. Esto resultó después de mirar el código de látex generado.
Es decir, hubo casos en que el mismo bloque se colocó en documentos diferentes de manera un poco diferente.
Otro punto relacionado con el alfabeto cirílico, es decir, el uso del idioma ruso. Como se mencionó anteriormente, para usar el idioma ruso, resultó ser suficiente para especificar babel ruso en el encabezado. Pero encontramos algunas rarezas, por ejemplo, no había resaltado en negrita y otras rarezas de formato. Inicialmente, pecamos por el hecho de que el ruso se especifica en mayúsculas y no en una plantilla. Comenzaron a estudiar el problema. Resultó que, en el buen sentido, no solo necesitas usar
\usepackage[russian, english]{babel}
pero también
establecer fuentes \usepackage[T1,T2A]{fontenc} \usepackage[utf8]{inputenc}
Pero incluso después de hacer esto, no fue posible rectificar la situación. Resultó que no todos los conjuntos de fuentes contienen todas las opciones de representación, en particular el nuestro no contiene negrita, cursiva, etc. en otros formatos. Como no había una solución simple para el problema, pensamos y pospusimos el problema hasta tiempos mejores. Bueno, dado que queríamos usar un marcado limpio (es decir, sin especificar comandos de látex), creamos una plantilla común para ambos idiomas, y la indicación sobre el idioma ruso se puso en el encabezado.
Solo unas pocas palabras diré sobre la interfaz de la aplicación en sí. Como, como dije, las aplicaciones de consola nos son muy familiares y se empaquetan fácilmente en scripts. En realidad, la interfaz es simple, por supuesto, puede configurar muchas opciones, pero para nuestros propósitos es suficiente especificar una plantilla, una lista de archivos de entrada y un archivo de salida.
pandoc --template=embox_pandoc.latex <title file> <list of input markdown files> -o <output file>
En Internet puede encontrar que para generar pdf (u otro formato de salida) necesita un tipo de procesador usando la opción --pdf-engine = xelatex, pero de manera predeterminada se usa si el archivo de salida tiene la extensión pdf. Por lo tanto, tampoco necesitábamos esto.
Empacamos los scripts para ensamblar la documentación en un Makefile, para que se volviera bastante familiar. Y ahora, para obtener la documentación, puede configurar el entorno necesario, solo llame
make [en][ru]
En conclusión, algunas palabras sobre el sistema de control de versiones. El principio no es complicar (mantener simple) tratamos de adherirnos a todo. Y como la solución más simple era usar un repositorio separado en github,
lo hicimos . Esperamos que el uso de github mejore los comentarios de los usuarios. Después de todo, como sabe en Github, hay problemas en los que puede discutir las deficiencias y ofrecer sus ideas y direcciones.
¡Este proceso se lanzó recientemente, a pedido de muchos trabajadores! Logramos hacer las versiones en
inglés y
ruso del "inicio rápido", así como la
primera versión del manual de usuario ruso . El proceso en sí nos pareció más conveniente, por eso lo compartimos con el público.