Jordan Merrick es muy consciente de lo difícil que es conseguir que la gente lea la documentación. Como redactor técnico de 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", dice Merrick. "Son muy impacientes, quieren poder probar el producto lo antes posible, y la documentación es una barrera percibida para ello".
CONSEJOS PARA UNA DOCUMENTACIÓN MÁS ATRACTIVA
- Haga que la documentación sea fácil de encontrar y leer.
- Realizar revisiones de la documentación con otros miembros del equipo.
- Mantener la documentación para que esté siempre actualizada.
- No pierda el tiempo documentando productos que aún están en proceso de elaboración.
- Incluya documentación de alto y bajo nivel.
- Hazlo más interactivo.
- Incluya elementos visuales como vídeos y capturas de pantalla.
- Incorporar la importancia de la documentación a la cultura del equipo.
Pero para los desarrolladores y redactores técnicos que escriben la documentación para ayudar a otros a entender el diseño, la funcionalidad y la arquitectura de las aplicaciones, el fenómeno puede ser bastante frustrante. Dedican innumerables horas a documentar un producto para usuarios externos o internos, sólo para descubrir que casi nadie sabe que existe. Y al mismo tiempo, los usuarios hacen las mismas preguntas que usted previó y abordó en la documentación. Puede ser desmoralizante.
"Es un fenómeno del que somos bastante conscientes", dijo Merrick. Dijo que el reto siempre es: "¿Cómo nos aseguramos de que la documentación sea lo más atractiva posible para los usuarios?".
He aquí algunas sugerencias para conseguir que la gente lea realmente la documentación.
La documentación debe ser fácil de encontrar y leer
A veces, los equipos guardan la documentación del software en una oscura carpeta compartida escondida en un servidor poco utilizado, lo que agrava el problema. Si la documentación es difícil de encontrar, es poco probable que la gente se esfuerce por leerla.
Almacenar la documentación cerca del código base es una buena alternativa. Hace que la documentación sea más fácil de encontrar y, como los desarrolladores la ven más, también es más probable que la mantengan y la actualicen.
"He visto a muchas empresas poner su documentación junto a su código, dentro de sus repositorios o dentro de los archivos de código", dijo Matt Eland, instructor de Tech Elevator, un campamento de arranque tecnológico.
La estructura de la documentación también es importante, según Heather Natour, responsable de ingeniería, ventas y B2B en la plataforma inmobiliaria online Opendoor. La documentación que es muy larga y no incluye formas fáciles de navegar para los lectores puede hacer que la gente no la utilice.
Incluir una función de búsqueda en la documentación es útil, al igual que tener una estructura de documentación clara que establezca los contenidos e incluya descripciones generales de alto nivel y secciones diferenciadas. De este modo, los usuarios pueden hojear la información que les interesa en lugar de verse obligados a leerla entera.
La documentación debe tener secciones de resumen que indiquen el objetivo del documento, dijo Natour. "[Eso] permite a alguien mantener una comprensión de hacia dónde va un escritor y posiblemente saltar para encontrar lo que necesita".
¿Revisiones de código? Pruebe con las revisiones de la documentación.
Según Frédéric Harper, director de relaciones con los desarrolladores de la empresa de análisis de documentos Mindee, la documentación suele ser redactada a posteriori por los mismos ingenieros que han escrito el código. Y eso puede ser un problema.
"Hacen suposiciones como: 'No tenemos que entrar en detalles en esa parte', o 'Ni siquiera tenemos que explicar esa parte'", dijo Harper. "Piensa en tu público. Trátalos como si no supieran nada de lo que estás hablando".
"Piensa en tu público. Trátalos como si no supieran nada de lo que hablas".
Estos puntos ciegos de información pueden producirse cuando el redactor de la documentación no recibe la información adecuada. Jon Quigley, ingeniero de pruebas de software de la empresa de consultoría de software Value Transformation, dijo que, al igual que con las revisiones de código, es una buena idea incluir a otros revisores en el proceso de documentación, idealmente desde el principio, incluso mientras se escribe el código.
"No hay que dejar que una sola persona, o sólo un subconjunto de personas, lo escriba", dijo Quigley. "Todos los que se ven afectados por esto deben participar en su desarrollo".
Si un ingeniero de sistemas crea documentación sobre un sistema, por ejemplo, debe buscar la opinión de otros ingenieros que interactúan con el software de diferentes maneras. Esto no sólo hará que la documentación sea más útil para una mayor variedad de usuarios, sino que también mejorará el diseño del propio software.
No deje que la documentación se estanque
Los usuarios se apresuran a ignorar la documentación obsoleta. Y con razón, porque el tiempo que se dedica a leer documentación obsoleta es, en la mayoría de los casos, una pérdida de tiempo.
"Si la terminología ha cambiado o se hace referencia a cosas que ya no se aplican realmente, el lector puede descartarla por completo y no utilizarla", dijo Natour.
Los equipos de desarrollo deben contar con un proceso de mantenimiento y actualización de la documentación para no crear otra barrera para los usuarios, dijo.
"Nos hemos dado cuenta de que la documentación obsoleta genera frustración. Y eso hace que los usuarios se vayan a otra parte".
En la empresa de consulta de datos Deephaven Data Labs, los ingenieros han configurado su sistema para realizar pruebas nocturnas de la documentación y del código, explica Amanda Martin, ingeniera de relaciones con los desarrolladores de la empresa. Deephaven crea documentación para usuarios externos, que son a su vez desarrolladores, por lo que la empresa se toma la documentación muy en serio.
Los ingenieros de Deephaven almacenan su documentación en GitHub junto con el código base y todas las noches se realizan pruebas con los ejemplos de fragmentos de código de la documentación. Esto garantiza que la documentación nunca estará desfasada con respecto al código de su producto.
"Nos hemos dado cuenta de que la documentación obsoleta genera frustración. Y eso hace que los usuarios se vayan a otra parte", dijo Martin.
Aunque no todas las empresas disponen de los recursos necesarios para realizar pruebas con su documentación, los equipos de desarrollo deberían dar prioridad a mantener la documentación actualizada en la medida de lo posible. Los desarrolladores pueden adquirir el hábito de actualizar la documentación existente tras los cambios de código correspondientes.
No todos los productos necesitan el mismo nivel de documentación
Andreas Nomikos, ingeniero de software de la plataforma de mensajería de IA Connectly, cree que es posible tener demasiada documentación. Si el producto aún está en fase de cambio, quizá no tenga sentido dedicar mucho tiempo a la documentación detallada, afirma.
"En los equipos de producto, normalmente el ritmo de cambio en la base de código es demasiado rápido", dijo Nomikos. "Invertir mucho tiempo en la documentación no produce un buen retorno de la inversión porque puedes estar construyendo algo y eso cambia en seis meses".
En esos casos, suele ser una mejor estrategia utilizar métodos más informales de formación e incorporación de nuevos desarrolladores. Los desarrolladores que acaban de incorporarse a un proyecto pueden aprender programando en parejas con desarrolladores más experimentados y trabajar en tareas sencillas que les introduzcan en el código base. Eso no requiere tanto mantenimiento ni tiempo de preparación.
Si, por el contrario, los desarrolladores están creando un recurso compartido que utilizan muchos otros equipos de la empresa, invertir en documentación puede tener más sentido, dijo Nomikos. Los equipos de infraestructura, por ejemplo, crean productos que se utilizan internamente y no se modifican durante años. En esos casos, los desarrolladores deben esforzarse más en crear una documentación clara y detallada, porque muchos usuarios necesitarán consultar el mismo documento durante mucho tiempo.
Una buena documentación debe abordar el por qué
Los desarrolladores necesitan una variedad de estilos de documentación para adaptarse a las necesidades de los diferentes usuarios.
"Cada usuario llega a ese software con un bagaje diferente y, a menudo, con un objetivo distinto", dijo Martin.
Algunas personas quieren una visión general de alto nivel de lo que hace el software y cómo se compara con otras herramientas, mientras que otros usuarios son desarrolladores que buscan guías de bajo nivel que enumeran las entradas y salidas de ciertas funciones que están llamando. Cuando Eland utiliza la biblioteca de aprendizaje automático de Dotnet, por ejemplo, consulta tanto la documentación técnica de bajo nivel -lo que él llama "documentación de estilo de referencia"- como la documentación de alto nivel que explica el diseño general. Si sólo utilizara los documentos de referencia, podría perderse fácilmente.
"Todos parecen tener el mismo nivel de importancia porque todos están en la misma lista y está todo en orden alfabético", dijo Eland. "No sé en cuál de ellos profundizar primero".
Pero, en cambio, si empezara por leer la documentación de alto nivel, como una página de "inicio", podría servir como un directorio que aclare el propósito del proyecto y le dirija a recursos adicionales. Especialmente en estos documentos de alto nivel, es importante captar el porqué. Si los usuarios pueden entender la visión de los desarrolladores para su aplicación al leer la documentación, entonces será más probable que entiendan las peculiaridades de implementaciones específicas que pueden parecer extrañas fuera de contexto.
Esto puede ser incluso tan simple como enumerar las métricas del sistema: al dar a los lectores una comprensión de las capacidades de una aplicación, puede ayudarles a construir un modelo mental de lo que la aplicación puede hacer.
Haga que la documentación sea más interactiva
Algunas de las documentaciones más eficaces para los desarrolladores son interactivas y permiten a los lectores codificar para ayudar a absorber la información. El mero hecho de tener texto puede disuadir a los desarrolladores de utilizarlo.
"Los desarrolladores somos gente de acción, queremos codificar y hacer que las cosas sucedan", dijo Harper. "¿Por qué tengo que ir a la documentación y leerlo todo cuando puedo ir a codificar y probarlo?".
Tom Ahi Dror, cofundador de la empresa de documentación continua Swimm, dijo que la documentación acoplada al código que incluye tanto texto explicativo como referencias a la base de código puede acicalar un documento de referencia que de otro modo sería aburrido. "Explican el código o utilizan trozos del mismo como ejemplos".
"Los desarrolladores somos gente de acción, queremos codificar y hacer que las cosas sucedan... ¿Por qué tengo que ir a la documentación y leerlo todo cuando puedo ir a codificar y probarlo?"
Su empresa, Swimm, está especializada en crear herramientas que facilitan a los desarrolladores la vinculación de la documentación con el código. Los enlaces a la documentación técnica detallada aparecen directamente en los editores de código y los enlaces al código también aparecen en la documentación. Los desarrolladores que escriben la documentación pueden seguir una estrategia similar añadiendo enlaces y fragmentos de código en el texto del documento para facilitar su comprensión a los lectores.
En Retool, Merrick dijo que suele tratar de escribir documentación interactiva para que el usuario pueda crear algo sencillo en cinco o diez minutos.
"Esa sensación de logro aumenta el compromiso y la confianza, hasta el punto de que el usuario tiene ganas de aprender más, en cuyo caso, va a comprometerse más con la documentación", afirma.
Es importante elegir ejemplos sencillos y reales que los usuarios puedan encontrar al crear la documentación interactiva, dijo.
"Construir usos del producto en el mundo real es mucho más atractivo porque los usuarios pueden relacionar más fácilmente sus necesidades con el caso de uso", dijo Merrick. Animó a los desarrolladores a crear ejercicios interactivos, como la puesta en marcha de herramientas de gestión de las relaciones con los clientes o cuadros de mando.
Aproveche los elementos visuales y los vídeos
Los vídeos y los elementos visuales también pueden mejorar la documentación. Los desarrolladores que escriben la documentación utilizando Markdown pueden aprovechar las características del lenguaje para incrustar enlaces, vídeos e imágenes directamente en el archivo de documentación, dijo Eland.
"Muchas cosas que podrían requerir párrafos para ser descritas - o puedes grabar un GIF rápido o un video de YouTube", dijo Eland. "La gente lo ve y dice: 'Huh, OK, eso tiene sentido'".
La documentación basada en texto también tiene ventajas, como la posibilidad de búsqueda, pero incluir tanto imágenes como texto puede ser muy útil para las personas que aprenden de diferentes maneras. Los vídeos y las capturas de pantalla ni siquiera llevan mucho tiempo de creación y pueden ahorrar tiempo a los desarrolladores.
"Un ingeniero de mi equipo hizo una grabación rápida de sí mismo caminando a través de la depuración de un tipo específico de problema, simplemente bajó la barrera para crear y compartir información", dijo Natour. "Poder obtener los beneficios de ese tipo de interacciones en un formato de vídeo rápido y reutilizable fue realmente útil. Lo hizo más accesible para que la gente lo consultara".
Fomentar una cultura de la documentación
Independientemente de lo bien que se documenten los proyectos, gran parte de lo que determina si la documentación se utiliza y se mantiene se reduce a la cultura de desarrollo. Según Quigley, esta cultura puede medirse en función de si la documentación tiene realmente prioridad cuando los plazos son ajustados y surgen problemas críticos que exigen atención.
Los equipos pueden establecer una política para redactar los documentos de requisitos, tener un cuidadoso proceso de revisión del diseño e incluso hacer revisiones de la documentación. Pero si el equipo hace caso omiso de esas consideraciones cada vez que un proyecto está bajo presión de tiempo, entonces esas políticas no se mantendrán por mucho tiempo.
Por ello, los directivos deben promover una cultura de documentación dando prioridad a la misma y reservando siempre un tiempo durante los ciclos de desarrollo para actualizar y mantener la documentación existente, independientemente de la situación.
"Si no se entiende bien la cultura, nada más que se diga o se ponga en blanco y negro va a importar", dijo Quigley.