Documentación técnica de software y de procesos: manuales, SOP y especificaciones

La documentación técnica de software es el conjunto de textos y diagramas que explican qué hace un sistema, cómo está armado, cómo se usa y cómo se mantiene. Cuando existe, un sistema sobrevive a los cambios de equipo. Cuando no existe, todo el conocimiento depende de que una persona se acuerde, y esa persona un día se va de vacaciones, se enferma o cambia de trabajo.

Es un trabajo que casi todas las empresas postergan, porque nunca es urgente hasta que lo es. Los síntomas se parecen: nadie se anima a tocar el sistema por miedo a romperlo, cada incorporación al equipo lleva semanas de explicaciones verbales, los errores se repiten porque no queda registro de cómo se resolvieron y cambiar de proveedor se vuelve casi imposible.

Escribimos la documentación pensando en quien la va a leer, que casi nunca es quien la escribe. Por eso usamos lenguaje claro, ejemplos reales de tu operación y un orden que permita encontrar lo que se busca en pocos minutos. Una documentación larga que nadie consulta es peor que una corta que se usa.

Un manual de usuario enseña a hacer tareas, no a admirar un sistema. El que nosotros escribimos está organizado por lo que la persona quiere lograr (por ejemplo "cargar un pedido" o "anular una factura"), no por el menú del programa. Cada tarea lleva los pasos en orden, capturas de pantalla actuales y una sección de qué hacer si algo falla.

También hay tres formatos que combinamos según el caso:

• Un manual completo, para consultar cuando surge una duda.
• Guías rápidas de una página para las tareas diarias, que se pueden imprimir o dejar en un lugar visible.
• Un listado de preguntas frecuentes con las dudas que realmente aparecen en las primeras semanas de uso.

Si el sistema lo construimos nosotros, el manual se arma mientras se desarrolla y se prueba con una persona de tu equipo que no participó del proyecto. Si no entiende un paso, el error es del manual y no de ella. También acompañamos la entrega con una sesión de capacitación para tu equipo.

Un SOP (procedimiento operativo estándar) describe cómo se hace una tarea de la forma acordada, para que se haga igual sin importar quién la ejecute. Sirve para formar a una persona nueva, para repartir tareas sin perder calidad y para que las cosas importantes no dependan de la memoria de alguien.

Un buen procedimiento incluye siempre lo mismo: para qué sirve, quién es responsable, qué se necesita antes de empezar, los pasos en orden, cómo se sabe que salió bien y qué hacer con las excepciones más comunes. No hace falta que sea largo; una página bien escrita suele servir más que diez.

Para escribir procedimientos que reflejen cómo se trabaja de verdad, hablamos con quienes hacen la tarea y la observamos antes de redactar. Si todavía no tienes los procesos ordenados, el paso previo es un relevamiento de procesos: documentar un proceso desordenado solo deja por escrito el desorden. Y si lo que buscas es que el procedimiento lo ejecute un sistema, la automatización de procesos empresariales es el paso siguiente.

La documentación funcional explica qué hace un sistema desde el punto de vista del negocio, sin entrar en el código. Es el documento que lee quien decide, quien administra el sistema o quien necesita saber, por ejemplo, qué pasa cuando se anula un pedido ya facturado o quién puede modificar un precio.

La especificación de requisitos es su versión previa a la construcción: define qué se va a hacer antes de hacerlo. Incluye los requisitos ordenados por prioridad, las historias de usuario (quién necesita qué y para qué), los criterios de aceptación que permiten decir "esto está terminado" y una lista explícita de lo que queda fuera. Esa última lista evita la mayoría de las discusiones sobre el alcance.

Escribir la especificación antes de programar cuesta unas horas y puede ahorrar muchas más. Con ella, el presupuesto de horas es más confiable, quien programa sabe exactamente qué construir y tú puedes comparar propuestas de distintos proveedores sobre la misma base. Esto es especialmente útil para sistemas de gestión a medida y para cualquier desarrollo que involucre a varias áreas.

Una situación frecuente: tienes un sistema que funciona, que construyó alguien que ya no está o que nunca dejó nada escrito, y necesitas modificarlo, cambiar de proveedor o simplemente dormir tranquilo. Documentar un sistema existente es posible, y empieza siempre por entender cómo funciona realmente.

Para eso revisamos el sistema desde dos lados. Por el lado del uso, conversamos con quienes lo operan y registramos qué hacen y qué casos especiales manejan. Por el lado técnico, analizamos cómo está construido, dónde están los datos, qué servicios externos usa y qué dependencias tiene. Con ambos lados armamos los documentos de la tabla de arriba que correspondan.

Hay un límite que conviene conocer: podemos explicar qué hace el sistema y cómo, pero no siempre podemos recuperar por qué se decidió algo, si nadie lo recuerda. Cuando eso pasa, lo marcamos en el documento como pendiente de confirmar y no lo inventamos. También señalamos los riesgos que aparecen en el camino, como accesos que solo conoce una persona o falta de copias de seguridad.

Una documentación desactualizada es peor que ninguna, porque da una confianza falsa. Por eso, además de escribirla, dejamos pautas para que se mantenga:

• Que cada documento tenga un responsable y una fecha de última revisión.
• Que el cambio de un procedimiento o de una función del sistema incluya actualizar el documento correspondiente.
• Que la documentación viva en un único lugar al que todos accedan, y no repartida en correos y carpetas personales.
• Que se revise cada tanto, con una reunión corta, qué quedó viejo.

Si lo prefieres, puedes contratar horas mensuales para que actualicemos la documentación junto con los cambios del sistema, o para el soporte de un sitio como el de mantenimiento de páginas web. En todos los casos, los documentos, los diagramas y los archivos fuente quedan a tu nombre y en formatos editables.