Por Tammy Xu
Jordan Merrick es muy consciente de lo difícil que es conseguir que la gente lea la documentación. Como escritor técnico para la plataforma de desarrollo de herramientas Retool, su trabajo consiste en crear documentación para los usuarios.
"A menudo bromeo diciendo que los usuarios nunca leen la documentación", dijo Merrick. "Son muy impacientes, quieren poder probar el producto lo más rápido posible, y la documentación se percibe como una barrera para eso."
Consejos para una documentación más atractiva:
La documentación debe ser fácil de encontrar y leer
Almacenar la documentación cerca del código base es una buena alternativa a las carpetas compartidas poco accesibles. Hace que la documentación sea más fácil de encontrar y, como los desarrolladores la ven con más frecuencia, también es más probable que la mantengan. Incluir funcionalidad de búsqueda y una estructura clara que muestre el contenido e incluya resúmenes de alto nivel permite a los usuarios hojear la información relevante.
¿Revisiones de código? Prueba las revisiones de documentación.
Al igual que con las revisiones de código, es una buena idea incorporar a otros revisores en el proceso de documentación—idealmente desde el principio, incluso mientras se escribe el código. "No dejes que una sola persona, o solo un subconjunto de personas, la escriba", dijo Jon Quigley. "Todo el que haya tenido contacto con este proyecto debería participar en su desarrollo."
No dejes que la documentación quede desactualizada
Los usuarios descartan rápidamente la documentación desactualizada. Los equipos de desarrollo deben tener un proceso para mantener y actualizar su documentación. En Deephaven Data Labs, los ingenieros ejecutan pruebas nocturnas tanto en la documentación como en el código. "Realmente notamos que la documentación desactualizada genera frustración. Y eso lleva a que los usuarios vayan a otro lado."
No todos los productos necesitan el mismo nivel de documentación
Andreas Nomikos, ingeniero de software en Connectly, cree que es posible tener demasiada documentación. "En los equipos de producto, la tasa de cambio en el código base suele ser demasiado rápida. Invertir mucho tiempo en documentación no produce un buen retorno de la inversión porque puedes estar construyendo algo que cambie en seis meses."
La buena documentación debe abordar el porqué
Algunas personas quieren una visión general de alto nivel, mientras que otros usuarios son desarrolladores que buscan guías de bajo nivel. "Cada usuario llega a ese software con un contexto diferente y, a menudo, con un objetivo diferente." Incluir una página de "primeros pasos" puede servir como directorio que aclare el propósito y apunte hacia recursos adicionales.
Haz la documentación más interactiva
"Los desarrolladores somos personas de acción, queremos programar y hacer que las cosas sucedan. ¿Por qué debería ir a la documentación y leerlo todo cuando puedo simplemente programar y probarlo?" La documentación acoplada al código que incluye tanto texto explicativo como referencias al código base puede animar un documento de referencia que de otro modo sería aburrido.
Fomenta una cultura de documentación
"Si no logras que la cultura sea la correcta, nada de lo que digas o pongas por escrito va a importar", dijo Quigley. Los gerentes deben promover una cultura de documentación reservando siempre tiempo durante los ciclos de desarrollo para actualizar y mantener la documentación existente, independientemente de la situación.
©️ 2025 Todos los derechos reservados. Connectly Inc. Creado con ❤️, globalmente.