Es probable que la documentación de su empresa carezca de muchos aspectos, pero con solo un poco de trabajo y orientación, sus desarrolladores pueden llevarla al siguiente nivel.
Si sus desarrolladores, diseñadores, administradores y miembros del equipo no documentan su trabajo, su negocio no está funcionando tan bien como debería. En pocas palabras, unos esfuerzos sólidos de documentación realmente pueden ayudar a mejorar el flujo de trabajo y la confiabilidad de sus procesos. Una buena documentación no sólo evita lagunas en la comprensión de cómo funciona algo, sino que también hace que sea mucho más fácil para cualquiera asumir un rol y ser eficaz.
El problema es que una mala documentación puede ser peor que ninguna documentación. Cuando la documentación está mal escrita, puede ser difícil de usar y puede confundir a los miembros del equipo hasta el punto de que no se puede hacer nada hasta que se resuelva ese tema específico.
Y la documentación no sólo se aplica a los desarrolladores. La documentación se puede utilizar para cualquier cosa dentro de su empresa, como por ejemplo:
- Cómo utilizar el software
- Cómo utilizar hardware
- Cualquier flujo de trabajo
- Mejores prácticas generales
- Integración del equipo
- RRHH y personal
Aunque la documentación puede llevar algo de tiempo, el esfuerzo vale la pena, ya que le ahorrará a su empresa un tiempo considerable a largo plazo, además de evitar confusiones y obstáculos en el futuro.
Dicho esto, ¿cómo pueden tus desarrolladores mejorar tu documentación? Echemos un vistazo a algunas ideas.
Desarrollar políticas de documentación.
Esto debería ser lo primero que haga para mejorar la documentación. Ya sea que esté comenzando este viaje desde cero o esté asumiendo la tarea de mejorar toda su documentación existente: tómese el tiempo para desarrollar políticas para el proceso y los resultados finales.
Para estas políticas, deberá decidir qué se incluye en la documentación, su público objetivo, las herramientas de documentación preferidas, la función de los comentarios, si la documentación se alojará en un sistema de control de versiones (como Git) y si la documentación Se adherirá a una guía de estilo específica.
Una vez que desarrolle estas políticas, asegúrese de que toda la documentación las siga al pie de la letra.
Usar voz activa
Para crear documentación concisa y fácil de seguir, sus desarrolladores deben comprender cómo utilizar la voz activa. Lo opuesto a la voz activa es la voz pasiva y reduce drásticamente la claridad, la coherencia y la eficiencia.
Un ejemplo simple de voz activa versus pasiva es el siguiente:
- Voz activa: Bob corrió un maratón.
- Voz pasiva: Bob corrió un maratón.
Cuando se utiliza la voz activa, el sujeto realiza la acción (Bob corrió una maratón). Cuando usas la voz pasiva, el sujeto sufre la acción (Bob corrió un maratón).
Quiere que cada frase de su documentación sea lo más clara y sencilla posible. No complique las cosas y no haga que el lector de la documentación tenga que esforzarse por lograr claridad.
Fomente el uso de títulos atractivos
Una buena documentación debe considerarse al mismo nivel que escribir cualquier tipo de contenido. Desea utilizar títulos atractivos para que el lector sepa exactamente qué sigue y qué esperar. Esto es especialmente cierto si tenemos en cuenta que todo el mundo, en todas partes, vive bajo una avalancha de contenidos. Debido a esto, los usuarios tienden a hojear mucho más que antes. Cuando utiliza títulos (y subtítulos) atractivos, el contenido se vuelve mucho más fácil de leer y absorber.
Todo lo que pueda hacer para aliviar la carga de quienes dependen de la documentación debe considerarse obligatorio.
Deja atrás las palabras de moda y las siglas
Al adoptar el uso de títulos atractivos, evite depender de palabras de moda. Esto es especialmente importante en tecnología porque no todo el mundo entiende todas las palabras de moda y acrónimos.
Al escribir documentación, es importante abordarla como si quien la leyera no la conociera y no estuviera familiarizado con el idioma actual. La documentación existe para ayudar a otras personas a comprender cómo su empresa hace y utiliza algo. Si sus desarrolladores dependen demasiado de palabras de moda y acrónimos, no hay garantía de que quienes lean los documentos comprendan lo que leen.
Agregar imágenes
Siempre que sea posible, agregue elementos visuales a la documentación. Esto es especialmente importante cuando documenta cómo funciona una herramienta GUI. En lugar de describir un gráfico, muestra una imagen. Al fin y al cabo, dicen que una imagen vale más que mil palabras y, en el ámbito de la documentación, este dicho es cierto.
Crear y usar plantillas
Una cosa que puede hacer para que todo este proceso sea exponencialmente más fácil es crear plantillas de documentación para que las utilicen sus desarrolladores. Esto reducirá drásticamente el trabajo que tendrán que hacer porque tendrán un documento simple que los guiará en la creación de su documentación.
Al crear estas plantillas, asegúrese de agregarles cualquier información que no solo garantice que su documentación permanezca consistente, sino que también haga que el contenido final sea más fácil de crear. Considere esta su forma de guiar a sus desarrolladores a través del proceso de documentación. Cuanto más fácil se lo pongas, más probabilidades habrá de que escriban la documentación y su trabajo seguirá tus directrices y será fácil de usar.
Conclusión
La creación de documentación sólida debe estar en la parte superior o cerca de ella en la lista de cosas que son importantes para la eficiencia de su empresa. Con un proceso de documentación sólido implementado, todo funcionará mejor. A sus desarrolladores no solo les resultará más fácil crear documentación, sino que aquellos que dependen de la documentación tampoco tendrán que luchar para descifrar el significado o la intención de lo que están leyendo.
