Elige las métricas adecuadas para tu proyecto

El objetivo de esta guía es ayudar a las organizaciones a comprender qué tipos de problemas se podrían resolver con una mejor documentación y cómo elegir las métricas adecuadas para los proyectos de documentación.

Fase actual:
Casos de éxito publicados. Consulta el cronograma.

Indica cuál es el problema

Antes de elegir una métrica, asegúrate de comprender bien el problema que estás tratando de resolver. Brinda la mayor cantidad posible de detalles.

  • “Las solicitudes de extracción para nuestra documentación de integración tardan demasiado en combinarse. Los colaboradores se rinden y se van”.
  • “Vemos demasiados problemas abiertos para obtener ayuda para comprender los códigos de error”.
  • "Nuestra canalización de CI/CD es inestable. Demasiados tests fallan por razones que no se comprenden bien".
  • “La gente parece gruñón en nuestras reuniones semanales”.

Desarrolla una hipótesis

Busca la causa y el efecto. ¿Cuál podría ser la causa del problema que mencionaste? Ten en cuenta que los problemas pueden tener varias causas o superponerse.

  • “Lleva mucho tiempo combinar las solicitudes de extracción para la documentación de integración porque no tenemos una guía clara sobre el estilo. Los revisores posponen la revisión de la PR porque no saben qué hacer o se comunican con los colaboradores sobre el formato".
  • “Los usuarios tienen que abrir problemas porque no pueden encontrar información sobre los códigos de error en la documentación”.
  • “Nuestras pruebas de CI/CD fallan porque nos encontramos con limitaciones de planes y tiempos de espera de nuestro proveedor”.
  • “Las personas están de mal humor en nuestras reuniones semanales porque se realizan a las 5:30 a.m. en su zona horaria”.

Proponer una solución

¿Es un problema que se podría resolver con una documentación nueva o mejor?

  • “Si tuviéramos una guía de estilo, los responsables de confirmación podrían revisarla antes de enviar sus solicitudes de cambios. Los revisores sabrían qué verificar. Los revisores y colaboradores no tendrían que discutir sobre el formato, el tono y el estilo".
  • “Si tuviéramos documentación sobre los códigos de error, los usuarios podrían encontrar sus respuestas allí, en lugar de abrir problemas”.
  • “Hmm, no parece que una mejor documentación resolvería nuestro problema de CI/CD”.
  • "Podríamos comenzar cada reunión con un chiste de "Toc toc". Crear una colección de chistes de "pregunta y respuesta" nos ayudaría a comenzar nuestras reuniones con una sonrisa".

Sé específico

¿Puedes cuantificar el problema?

  • "¿Qué significa realmente "tarda demasiado en combinar las PR"? ¿Dos meses? ¿Dos semanas? ¿Cuánto tiempo esperarán los colaboradores la revisión antes de darse por vencidos?".
  • "¿Cuántos problemas relacionados con códigos de error son "demasiados problemas"?"
  • "Hmmm… ¿qué tan malhumorado es "demasiado malhumorado"?"

Cómo verificar la capacidad de medición

¿Cómo verificarías la métrica propuesta? ¿Se puede medir con facilidad y precisión? ¿La medición depende de quién la realiza?

  • “Podemos medir fácilmente cuánto tiempo lleva abierta una solicitud de extracción y cuánto tiempo pasó desde que se solicitó una revisión. No podemos medir exactamente cuándo un colaborador se da por vencido".
  • “Podemos contar cuántos problemas están etiquetados como "error-code" o buscar el texto del código de error en los problemas”.
  • “Realmente, no podemos medir el mal humor de las personas de una manera táctil o precisa”.

Cómo agregar una métrica secundaria

¿Hay otras métricas que te ayuden a comprender si tu documentación está resolviendo el problema? ¿Tu métrica objetivo es la misma en todos los casos?

  • "Las PR más largas tardan más tiempo en revisarse. Deberíamos tener diferentes umbrales para diferentes tamaños de PR. Queremos medir el tiempo de combinación de PR pequeñas, medianas, grandes y gigantescas".
  • “Podríamos verificar cuántas visitas recibe nuestra documentación de códigos de error y ver si esa cantidad se correlaciona con menos problemas abiertos”.

Elige un período

  • “Creemos que dos semanas es un tiempo razonable para combinar PR de tamaño pequeño a mediano, y todas las PR deben combinarse en un mes. Por lo tanto, mediremos cada dos semanas".
  • “No tiene sentido actualizar la cantidad de problemas relacionados con códigos de error todos los días, ya que nuestro tiempo típico para cerrar un problema es de una semana. Lo mediremos semanalmente".

Fija objetivos

¿Cuánto cambio deberías ver en la métrica seleccionada para decir que el proyecto fue un éxito? Considera establecer objetivos cuantitativos para las métricas que elegiste.

  • “Si cumplimos con nuestro objetivo de cerrar cada PR nueva en menos de un mes, eso sería un éxito. Si nuestro tiempo promedio para cerrar PR grandes disminuyera en dos semanas, sería un gran éxito".
  • "Idealmente, no veríamos problemas nuevos relacionados con errores. Sin embargo, consideraremos que nuestro proyecto tuvo éxito si vemos una disminución del 50% en la cantidad de problemas relacionados con errores que se abren".