Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- The Linux Foundation
- Redactor técnico:
- boro
- Nombre del proyecto:
- Rediseñar el alojamiento y la generación de la documentación, y la reestructuración de las páginas de introducción y las guías para desarrolladores
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Resumen :
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 resolverá los problemas comunes que encuentran al usar el software. También reduce los costos 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 que el producto y el equipo de desarrolladores están en buenas condiciones.
Sin una buena documentación, es posible que el usuario no sepa cómo hacer todo lo anterior de manera efectiva y eficiente. La documentación puede desempeñar un papel fundamental para garantizar el éxito de un producto, ya que una buena comunicación es y siempre será el centro de cualquier empresa o producto, y una buena documentación solo toma esa comunicación y la coloca en un marco de trabajo manejable al que todos pueden acceder para tener éxito.
Cada sitio de documentación necesita una buena canalización de flujo de trabajo de compilación y alojamiento. En una organización como AGL, con varias versiones y mucha documentación elaborada, los archivos de documentación (Markdown) 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 documentos de AGL se basa en una colección de archivos Markdown recuperados de varios repositorios.
- Actualmente, las páginas de documentos se alojan dentro de las fuentes individuales como Markdown con el motor del proyecto de Cordova.
- Esto genera una configuración de cuatro repositorios para el proceso de compilación y alojamiento 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 (Markdown [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) para documentos y guías generales.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : Se implementó el repositorio de páginas de GitHub 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 recuperado_files.yml ubicado en docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- 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]
- La sección section_version.yml contiene los vínculos a todos los archivos YAML de libros y procede a recuperar todos los archivos YAML de libros de repositorios remotos a docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Los archivos YAML del libro contienen todas las URL a tus archivos de Markdown del repositorio remoto.
- En cuanto se recuperan todos los archivos Markdown, las herramientas procesan la generación del sitio web de documentos 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 ni para los desarrolladores, en especial para los colaboradores nuevos. Esta canalización del flujo de trabajo (de compilación y alojamiento) puede simplificarse y optimizarse mucho más para que los desarrolladores se enfoquen en la parte de la documentación en lugar de mantener la generación de documentación y el flujo de trabajo de implementación.