El equipo de ingeniería de la plataforma de Canonical ha estado trabajando duro para hacer documentos en torno a Rockcraft y Charmcraft Soporte nativo para marcos de aplicaciones web como Blask y Django. Este es parte del objetivo de Canonical de escribir documentos de alta calidad y mejorar con el tiempo a través del proceso de diseño y desarrollo. Una forma en que mejoramos la documentación es interactuar con los miembros de nuestro equipo y las comunidades externas. Sus perspectivas y comentarios proporcionan información valiosa sobre el diseño de nuestro producto, arrojando luz sobre cualquier explicación confusa y mejorando la experiencia del usuario de la herramienta (UX).
Nos centramos en hacer este documento fácil de usar, pero ¿cómo nos aseguramos de que nuestra documentación realmente beneficie a los lectores?
Hemos estado probando tutoriales para varios marcos que apoyamos desde noviembre pasado, con un total de 24 reuniones de UX (¡hasta ahora!). Estos participantes pasaron un valioso tiempo y esfuerzo trabajando en nuestros tutoriales, lo que nos permitió observar sus intentos y recopilar comentarios sobre instrucciones y explicaciones.
Cómo elegimos los participantes
Creamos soporte de marco de aplicaciones web a través del punto de entrada familiar para la mayoría de los usuarios: el desarrollo de aplicaciones web como una introducción accesible al producto estandarizado. Nuestro objetivo es atraer a los usuarios de ingenieros experimentados a nuevos inmigrantes. Para hacer esto, trabajamos con equipos internos (como la Web, que usan los productos de especificación todos los días) e interactúan con desarrolladores externos a través de comunidades y conferencias en línea. Para garantizar que nuestros documentos satisfagan las necesidades del mundo real, buscamos activamente comentarios de aquellos que no están familiarizados con las normas. Incluso probamos experiencias con estudiantes universitarios para confirmar que es accesible en todos los niveles de habilidad.
Reunión
Después de reclutar a cada participante, nos embarcamos en la fase más importante: la reunión en sí. ¡Hemos creado estas reuniones para proporcionar a los participantes una experiencia consistente y cómoda y alentar comentarios honestos sobre todo y todo! – En el tutorial.
Una sesión típica comienza con algunas preguntas rápidas para comprender los antecedentes de cada participante, por lo que podemos relacionar su experiencia con ella. Luego, comenzamos este tutorial. Observamos lo que los participantes notaron, cómo explicaron las instrucciones y los obstáculos que encontraron. Después de completar el tutorial, proponemos un conjunto de preguntas posteriores a la sesión para recopilar sus comentarios generales y explorar si las herramientas cumplen con sus expectativas para el marco ascendente.
Nuestro conocimiento de Document UX
Durante las 24 reuniones, sentí todo el alcance de las emociones humanas. Primero, escribir y publicar documentos crean una gran impotencia: una vez que el mundo ha publicado los documentos, ¡no hay nada que pueda hacer para ayudar a mis lectores! Me resulta difícil ver a los usuarios encontrar problemas que no puedo ayudarlos a resolver. Afortunadamente, los ingenieros están allí para proporcionar asistencia, aunque incluso de alguna manera no es suficiente. El curso es una oportunidad de aprendizaje indefensa que acepto el papel del autor.
Además de la impotencia, hay muchos momentos en los que siento pánico. Existe un elemento de riesgo para los documentos: a veces, argumenté para los cambios de documentos que proporcionarían mejores UX o mitigarían la confusión, solo deja que esos cambios exploten en tiempo real. Aprendí a mantener mi cara recta y acepté cualquier crítica o retroalimentación sobre los cambios que presioné. Definitivamente vale la pena probar nuevas ideas (al menos en la documentación), pero se convierten en calidad Ideas que han sido probadas por UX.
La mayoría de las veces, la reunión es silenciosa y me esfuerzo por concentrarme en los participantes y su comportamiento. En el tutorial, los usuarios tienen que esperar muchos puntos: descargar software, rocas y empaque de encanto para implementar sus aplicaciones, etc. Es muy tentador ver y centrarse en otras actividades en esos momentos, pero que yo sepa, las observaciones y detalles importantes pueden aparecer en cualquier momento y en la etapa. Incluso en los momentos más inofensivos, la atención también es una parte importante para comprender las experiencias de los participantes y sus comentarios.
Los participantes proporcionaron comentarios perspicaces sobre las herramientas y la documentación. Estos son algunos de los temas más comunes que hemos notado:
- Durante el examen con estudiantes universitarios, descubrimos que estos participantes estaban atrapados cuando se les pidió que creara un nuevo archivo de texto desde la terminal. Esta sesión marca su primer uso de un editor de texto terminal, y no tuvimos en cuenta este momento importante en la descripción. (¡También me siento muy en pánico en estos momentos!)
- Los participantes que trabajan en la máquina ARM64 comentaron sobre la experiencia incompleta, ya que la parte posterior de este tutorial solo es aplicable a las máquinas AMD64.
- Encontramos lugares comunes donde los participantes perdieron la guía, lo que llevó a su experiencia de problemas. Los participantes notaron que las instrucciones fueron «enterradas» en el texto y esperaban que el tutorial enfatizara mejor su importancia e impacto.
- Los participantes externos solicitaron más explicaciones sobre los productos normativos y cómo funcionan las herramientas: tenían curiosidad e interesados en investigar el «por qué» detrás del tutorial.
Priorizar y recibir comentarios
Para cada reunión, finalmente incluimos todas las observaciones en los documentos individuales. Luego recopilamos todos los comentarios y sugerencias directas en el archivo principal; Para el tutorial de Flask, el documento principal de comentarios cubre 16 páginas. A partir de ahí, el líder del proyecto, el diseñador de UX, el autor tecnológico (¡yo mismo!) Discutió los comentarios con el ingeniero para determinar cómo lo integraremos. Al priorizar la retroalimentación, consideramos las siguientes consideraciones:
- Bloquear el problema: Priorice la retroalimentación que señala problemas importantes.
- Eventos aislados: Identifique que se necesitan más comentarios de investigación.
- Diseño de compensaciones: Seleccione la retroalimentación de respuesta basada en el diseño específico realizado.
Con el tiempo, incorporamos comentarios en pequeños lotes, priorizando los principales bloqueadores y errores tipográficos. De esta manera, podemos resolver el problema más rápido, ¡lo que significa que nuestros lectores obtienen los beneficios de inmediato!
Encontramos que los cambios propuestos por las conferencias de UX tempranas mejoraron la calidad y los resultados de los cursos posteriores. Las trampas comunes en sesiones anteriores ya no son un problema. Hay menos preguntas sobre cómo funciona la herramienta. Y, algunos estarán encantados de escuchar, los usuarios que usan la máquina ARM64 pueden hacerlo a través de todo el tutorial.
Participar: ayúdanos a mejorar
Siempre hay mejoras en nuestra documentación, y estas reuniones de UX son una excelente manera de incluir miembros de la comunidad y hacer que nuestra documentación sea más accesible. Si está interesado en involucrarse, contáctenos en nuestro canal de Matrix Public.
