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:
- Open Collective
- Escritor técnico:
- Anna e só
- Nombre del proyecto:
- Mejorar la documentación de ayuda general
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Primeras impresiones Es común encontrar páginas de documentación que contienen instrucciones sin contenido multimedia complementario (videos, GIFs o imágenes), mientras que otras secciones del mismo capítulo tienen entradas más completas. Por ejemplo, Editar colectivo solo se compone de instrucciones, mientras que Agregar host fiscal incorpora contenido multimedia complementario.
En las páginas que consulté, no se describe ningún contenido multimedia con el atributo texto alternativo. La falta de descripciones de imágenes dificulta la comprensión completa de la documentación para las personas que usan lectores de pantalla y para quienes tienen conexiones a Internet más lentas, en las que es posible que no se cargue ningún contenido multimedia.
Algunas secciones de la documentación combinan preguntas frecuentes y instrucciones directas para navegar por la interfaz de usuario, como Cambiar el host fiscal. Dado que no hay un índice en la interfaz de la documentación, un usuario que conozca las consecuencias de un cambio en los registros de registro y solo quiera instrucciones objetivas puede percibir la documentación como demasiado extensa y tangencial.
Aunque el lenguaje de la documentación técnica es bastante coherente, en la Guía de estilo disponible públicamente no se proporciona mucha información acerca de cómo se debe escribir la documentación. Dado que la página Contribuir menciona contribuciones a la documentación técnica, tanto Open Collective como los posibles colaboradores se beneficiarían de lineamientos más completos.
Propuesta Propongo que se revisen las páginas de ayuda de los usuarios para que se replantee su presentación y su estructura actual.
Metodología y cronograma Quiero mejorar la documentación de Open Collective trabajando junto con la comunidad para promover ciclos de comentarios continuos de diversa duración.
Período de vinculación con la comunidad (del 1 de agosto al 1 de septiembre de 2019): Conoce a la comunidad de Open Collective. Entrevistar a miembros activos de proyectos destacados y iniciales y hacerles preguntas sobre el estado actual de la documentación (Informe n.o 1). Tomar nota de todos los sistemas internos que se usan para hacer un seguimiento de las consultas y los problemas, y el proceso para documentarlos en los Documentos de Open Collective (Informe n° 2). Evaluación de los problemas latentes en la versión actual de la documentación y preparación de un plan para solucionarlos (Informe n° 3).
Del 2 al 6 de septiembre: Primer ciclo de comentarios y ajustes, en el que se tendrán en cuenta todos los comentarios y sugerencias que hizo la comunidad durante el período de vinculación. ¿Nuestro plan está bien? ¿Hay algo que deba cambiar? (Informe n.o 4)
Del 9 al 20 de septiembre: Desarrollo de la prueba de concepto con el capítulo menos poblado de la documentación. Borrador de una guía de estilo pública (informe n.o 5).
Del 23 al 25 de septiembre: Envío de la prueba de concepto para su evaluación (grupo cerrado).
Del 26 al 27 de septiembre: ¿Necesita nuestro concepto de prueba algún ajuste antes de publicarlo? ¿Necesitamos más tiempo? Ajusta según corresponda. (Informe n° 6)
Del 30 de septiembre al 9 de octubre: Se publica la prueba de concepto. Segundo ciclo de comentarios (grupo público).
Del 10 al 15 de octubre: Ciclo de evaluación y ajuste final de la prueba de concepto. (Informe n.o 7)
Del 16 al 20 de octubre: Pequeña pausa en las actividades [1].
Del 21 de octubre al 23 de noviembre: La Guía de estilo pública es definitiva (Informe n° 8). Aplicación de todas las instrucciones presentes en la Guía de estilo a todas las páginas de la documentación del usuario (Informe n° 9). Informe en el que se evalúan todas las actividades realizadas y se hacen más recomendaciones para la comunidad (Informe n° 10).
La duración del proyecto puede extenderse si se solicita.
[1]: Viaje planificado antes de mi temporada de solicitud de Documentos de Google.
Entregas - Diez informes públicos sobre las actividades realizadas - Una guía de estilo pública que pueden usar Open Collective y los colaboradores externos - Páginas de documentación del usuario renovadas