Cómo desarrollamos documentación en un proyecto abierto de Embox

imagen 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.

Source: https://habr.com/ru/post/445792/


All Articles