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:
- Open Collective
- Escritor técnico:
- Anna e só
- Nombre del proyecto:
- Mejora 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 contengan instrucciones sin contenido multimedia complementario (videos, GIF, imágenes, etc.), mientras que otras secciones del mismo capítulo tienen entradas más completas. Por ejemplo, Edit Collective consta solo de instrucciones, mientras que Add Fiscal Host incorpora contenido multimedia complementario.
En las páginas que exploré, no se describe ningún contenido multimedia con el atributo de texto alternativo. La falta de descripciones de imágenes dificulta la comprensión completa de la documentación para quienes usan lectores de pantalla y aquellas con conexiones a Internet más lentas en las que cualquier contenido multimedia podría no cargarse.
En algunas secciones de la documentación, se combinan las preguntas frecuentes y las instrucciones directas para navegar por la interfaz de usuario, como Change Fiscal Host. Como no hay un índice en la interfaz de documentación, un usuario que es consciente de las consecuencias de un cambio en los registros de registro y solo desea instrucciones objetivas puede percibir la documentación como detallada y demasiado tangencial.
Aunque el lenguaje de la documentación técnica es bastante coherente, los documentos de la Guía de estilo disponibles públicamente son muy poco sobre cómo se debe escribir. Dado que la página Contributing menciona las contribuciones a la documentación técnica, tanto Open Collective como los posibles colaboradores se beneficiarían de lineamientos más completos.
Propuesta Propongo una revisión de las páginas de ayuda de los usuarios, para replantear su presentación y estructura actual.
Metodología y cronograma Quiero mejorar la documentación de Open Collective trabajando junto con la comunidad en la promoción de ciclos de retroalimentación continua de distinta 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 que están en curso, haciéndoles preguntas sobre el estado actual de la documentación (Informe n.o 1). Toma nota de todos los sistemas internos utilizados para hacer un seguimiento de las consultas y los problemas, y del proceso para documentarlos en Open Collective Docs (Informe n.o 2). Evaluación de problemas latentes en la versión actual de la documentación y preparación de un plan para resolverlos (Informe n.o 3).
2 y 6 de septiembre: Primer ciclo de comentarios y ajuste, teniendo en cuenta todos los comentarios y las sugerencias de la comunidad durante el período de vinculación con la comunidad. ¿Nuestro plan está listo? ¿Hay algo al respecto que deba cambiar? (Informe n° 4)
Del 9 al 20 de septiembre: Desarrollo de una prueba de concepto con el capítulo menos propagado de la documentación. Borrador de una Guía de estilo pública (informe núm. 5).
23 y 25 de septiembre: Envío de la prueba de concepto para evaluación (grupo cerrado).
26 y 27 de septiembre: ¿Es necesario hacer algún cambio en nuestra prueba de concepto antes de publicarla? ¿Necesitamos más tiempo? Realiza los ajustes necesarios. (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° 7)
Del 16 al 20 de octubre: Pequeña pausa de las actividades [1].
Del 21 de octubre al 23 de noviembre: La Guía de estilo pública será definitiva (Informe n.o 8). Aplicación de todas las instrucciones presentes en la Guía de estilo a todas las páginas de documentación del usuario (Informe n.o 9). Informe sobre la evaluación de todas las actividades realizadas y otras recomendaciones para la comunidad (Informe n.o 10).
Es posible que se extienda la duración del proyecto si se lo solicita.
[1]: Viaje programado antes de la aplicación Temporada de Documentos.
Ítems - Diez informes públicos sobre las actividades realizadas - Una guía de estilo pública que tanto Open Collective como colaboradores externos pueden usar - Páginas de documentación del usuario renovadas