En esta página, se incluyen los detalles de un proyecto de redacción técnica aceptado para el programa Google Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- The Linux Foundation
- Redactor técnico:
- boron
- Nombre del proyecto:
- Rework the documentation hosting &generation and Restructure getting started pages and developer guides.
- Duración del proyecto:
- Duración estándar (3 meses)
Descripción del proyecto
Se puede abstraer :
La documentación está diseñada para ayudar a los usuarios finales y a los desarrolladores a usar un producto o servicio. Una buena documentación es muy importante porque proporciona una vía para que los usuarios aprendan a usar un software, sus funciones, sugerencias y trucos, y también resuelvan los problemas comunes que surgen cuando se usa el software. También reduce el costo de asistencia y forma parte de la identidad corporativa y de código abierto del producto. Una buena documentación es un signo de la salud del producto y del equipo de desarrolladores.
Sin una buena documentación, es posible que un usuario no sepa cómo realizar las acciones anteriores de manera eficaz y eficiente. La documentación puede desempeñar un papel fundamental para garantizar el éxito de un producto, ya que la comunicación excelente es y siempre será el centro de cualquier empresa o producto, y una excelente documentación solo toma esa comunicación y la coloca en un marco manejable al que todos pueden acceder para lograr el éxito.
Cada sitio de documentación necesita un buen flujo de trabajo de compilación y hosting. En una organización como AGL, con varias versiones y mucha documentación elaborada, los archivos de documentación (markdowns) se distribuyen en varios repositorios, lo que hace que la tarea de mantenerlos y actualizarlos sea increíblemente compleja y requiera mucho tiempo.
Estado actual :
- El sitio web de documentación de AGL se basa en una colección de archivos Markdown recuperados de varios repositorios.
- Actualmente, las páginas de documentación se alojan dentro de las fuentes individuales como Markdown con el motor del proyecto de Cordova.
- Esto lleva a una configuración de cuatro repositorios para el proceso de compilación y hosting de la documentación :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : Contiene la plantilla del sitio web de Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : Contiene herramientas para generar automáticamente un sitio web técnico a partir de archivos Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : Fuente (markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) para documentos generales y guías.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : Repositorio de páginas de GitHub implementado para el sitio de documentación [https://gist.github.com/growupboron/docs.automotivelinux.org].
- Una herramienta (secuencia de comandos) disponible en docs-tools [https://github.com/automotive-grade-linux/docs-tools] se encarga de recopilar y crear plantillas de todos los archivos Markdown según el archivo fetched_files.yml ubicado en docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- El flujo de trabajo actual de la generación del sitio web de documentación de AGL : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- El archivo section_version.yml contiene los vínculos a todos los archivos YAML del libro. Luego, recupera todos los archivos YAML del libro de los repositorios remotos al archivo docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Los archivos YAML del libro contienen todas las URLs a tus archivos Markdown del repositorio remoto.
- En cuanto se recuperan todos los archivos Markdown, las herramientas procesan para generar el sitio web de documentación de AGL en docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages], que se implementa de forma correspondiente.
- El proceso actual de mantenimiento de la canalización no es fácil de usar para los usuarios ni los desarrolladores, en especial para los colaboradores nuevos. Este flujo de trabajo (de compilación y hosting) se puede simplificar y optimizar mucho más para que los desarrolladores se enfoquen en la parte de documentación en lugar de mantener el flujo de trabajo de generación y la implementación de la documentación.