Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- Linux Foundation
- Escritor técnico:
- boro
- Nombre del proyecto:
- Reformula la documentación de hosting y generación y reestructura las páginas de inicio y las guías para desarrolladores.
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Se puede abstraer :
La documentación está diseñada para ayudar a los usuarios finales y desarrolladores a usar un producto o servicio. Una buena documentación es muy importante porque proporciona un camino para que los usuarios aprendan a utilizar un software, sus funciones, consejos y trucos, además de resolver problemas comunes que encuentran cuando lo utilizan. 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 una señal de buen estado del producto y del equipo de desarrolladores.
Sin una buena documentación, es posible que un usuario no sepa cómo hacer las cosas anteriores de manera efectiva y eficiente. La documentación puede desempeñar un papel fundamental para garantizar el éxito de un producto porque una buena comunicación es y será siempre el núcleo de cualquier negocio o producto, y una gran documentación solo toma esa comunicación y la coloca en un marco manejable al que todos pueden acceder para tener éxito.
Todo sitio de documentación necesita una buena canalización de flujo de trabajo de construcción y alojamiento, en una organización como AGL, con múltiples 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 complejo y demanda mucho tiempo.
Estado actual :
- El sitio web de documentos de AGL se basa en una colección de archivos de Markdown obtenidos de varios repositorios.
- Actualmente, las páginas de documentos están alojadas en fuentes individuales como Markdown a través del motor del proyecto Cordova.
- Esto conduce a la configuración de cuatro repositorios para la compilación de documentación y el proceso de hosting :
- 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 de Markdown.
- Fuentes de Documentos [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 de Markdown según el archivo fetch_files.yml ubicado en docs-webtemplate [https://github.com/automated-grade-linux/docs-webtemplate].
- Flujo de trabajo actual de la generación de sitios web de documentación de agl : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- La sección section_version.yml contiene los vínculos a todos los archivos yaml del libro y, luego, recupera todos los archivos yaml del libro de los repositorios remotos a la plantilla docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Los archivos YAML del libro contienen toda la URL que lleva a tus archivos de Markdown desde el repositorio remoto.
- Tan pronto como se recuperan todos los archivos de Markdown, el proceso de las herramientas para generar el sitio web de documentos de AGL se implementa en las páginas docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages].
- El proceso actual de mantener la canalización no es fácil de usar para los usuarios y desarrolladores, especialmente para los nuevos colaboradores. Esta canalización de flujo de trabajo (de compilación y hosting) se puede simplificar y optimizar de forma mucho más para que los desarrolladores se enfoquen en la parte de la documentación, en lugar de mantener el flujo de trabajo de implementación y generación de documentación.