Esta tercera y última parte de esta crónica viene luego de haber transcurrido bastante tiempo de las primeras dos partes debido, en gran medida, a mis actividades del día a día, que curiosamente durante los últimos días, han sido relacionadas con el tema central de la crónica: la documentación.
Recapitulemos…
En la primera parte he expuesto 6 motivos que el grueso de la gente que se dedica al desarrollo del software utiliza para argumentar que la tarea de crear documentación no solo consume mucho tiempo y recursos, sino que además, no tiene sentido o es meramente un producto que se solicita por tradición o por acuerdos comerciales.
En la segunda parte he tratado de desmentir algunos de estos puntos con casos prácticos, proponiendo escenarios donde se presentan diferentes tipos de documentación que no necesariamente es de carácter técnico, pero que siguen relacionados al día a día de esta maravillosa actividad profesional, y cuya ausencia, complica las operaciones de un equipo o deriva en problemas y retrabajos que nadie compensa.
En esta tercera entrega ahondaremos más en este particular, retomando la frase con la que se cierra la primera parte de la crónica: la documentación es engorrosa excepto cuando te encuentras en la necesidad de consultarla – y esta no existe.
Mi primer empleo formal como desarrollador de software
Era el año 2005. Yo tenía pocos meses de haber finalizado mis estudios de ingeniería y aunque no era una mente superdotada (aún no lo soy y estoy convencido de que no lo seré) la programación no era una tarea que se me complicara. En esos años conocía PHP, Visual Basic 6, Java para escritorio (con la version 1.4 SE y un poco de swing) y algunas otras cosas relacionadas.
En el verano de ese año, uno de mis mejores amigos me buscaba para participar con él en un proyecto de desarrollo en la capital del país. En ese entonces yo llevaba poco más de un año trabajando en un instituto donde ofrecen carreras técnicas «rápidas» de 2 años, como profesor de programación y enseñando a usar software como Adobe Flash, Visual Fox Pro, Visual Basic, Office, Photoshop.
La oferta de trabajar en desarrollo de software era más que tentadora; primero, porque estaba totalmente ligada al tipo de formación universitaría que había llevado, y en segundo lugar, porque la compensación ofrecida era 3 veces mayor a lo que yo podía ganar como profesor en el mismo tiempo. De modo que tras discutir la logística de transporte y algunos otros detalles menores, acepté.
Hubo inconvenientes, por supuesto, y el primero (que no nos detuvo) fue el lenguaje de programación; el proyecto se haría con 4GL. Si no tienes idea de qué es esto, yo tampoco la tenía. Es un lenguaje de programación de alto nivel enfocado en el desarrollo rápido de aplicaciones comercializado por IBM para en ese entonces, su motor de base de datos INFORMIX (hay otro de igual nombre para PROGRESS/OPENEDGE), que llamaremos «empresariales» y que utiliza interfaz de texto (así es, para línea de comando).
Antes de iniciar con el proyecto, nos comentaron que recibiríamos capacitación en la plataforma, por lo que no había de qué preocuparnos. Esa capacitación nos sería brindada un sábado de forma exhaustiva ya que el proyecto iniciaría días después.
La primera y única sesión de capacitación fue tan peculiar, que debe quedar para la posteridad (la mayor posible) y ser una referencia de lo que no se debe hacer:
El instructor llegó 3 horas tarde. Sí, TRES HORAS TARDE. Nos citaron a las 10am, el instructor llegó a la 1pm. ¿Lo esperamos por 3 horas? ¡Por supuesto! Esto no significa que estuvieramos de buen humor o que no hayamos estado haciendo toda suerte de comentarios negativos acerca del horario o por haber tenido que esperar bajo el sol en la calle (porque el instructor traía consigo las llaves del sitio donde se realizaría la capacitación). Nuestro próximo jefe estaba en comunicación con nosotros (mas no se apareció en todo el día) y nos garantizaba la llegada del susodicho, acompañado de numerosas disculpas por los inconvenientes. Si bien, la razón más importante de nuestra permanencia era estrictamente tener esa tan requerida capacitación (recuerda que la narración inicia en 2005, investigar en internet no era barato ni tan sencillo como ahora).
Finalmente llegó el instructor; no se disculpó por el horario. Parecía más bien que él había acordado esa hora y que nuestro jefe era quien había errado la coordinación. La sesión duró poco más de 40 minutos. Nos dijo el nombre de la plataforma, que si bien utilizaba el lenguaje de programación 4GL, en realidad se trataba de una plataforma que él llamada fourjs (léase four yeis). Nos dijo que nos proporcionaría un manual con ejemplos y ese día se limitaría a responder algunas preguntas:
-¿Funciona como PHP o ASP?
-Más o menos. No es interpretado, se compila, funciona más como Java.
-Leí que la interfaz es de solo texto, ¿es así?
-Tiene la interfaz así, pero se usará en formato web, hay formas de usarlo así.
-¿Se pueden hacer formularios dinámicos como en PHP?
-No; te acabo de decir que no se interpreta. La pantalla y la interacción con ella va compilada, no la puedes mover en tiempo de ejecución.
La sesión pronto se convirtió en un ir y venir de preguntas relacionadas a lo que sabíamos que se podía hacer en las plataformas que referí al inicio y a la constante respuesta negativa de parte del instructor. Nada de lo que se pensara como «dinámico» se podía hacer, ya que una característica de la plataforma era que tal cual se compilaba un componente, así se mostraba y ejecutaba.
Salimos del «centro de capacitación» con pesadumbre (y evidente molestia): 3 horas de espera, 40 minutos de negativas y más nada, salvo una clarificación y una promesa: la plataforma es fourjs, se les proporcionará un manual.
¿Dónde entra la documentación en esta parte de la crónica?
- Desde el inicio. Si existía, no nos proporcionaron (ni preguntamos por él, no sabíamos) algún documento que describiera el proyecto.
- El manual que nos ofrecieron nunca llegó.
Y finalmente, el motivo de mencionarla. Resulta que cuando llegamos al proyecto, no usaríamos fourjs, usaríamos Genero. El segundo era la evolución del primero; una plataforma comercializada por la empresa 4js que se basa en la especificación del lenguaje de programación 4GL (el de INFORMIX) modernizado con su propio compilador, máqina virtual y multitud de accesorios. El gran problema con el que nos encontramos fue que al iniciar el proyecto, asumían que ya conocíamos la plataforma (vaya, nos habían dado una sesión de capacitación y manuales…).
Afortunadamente, Genero venía acompañado de su «documentación». ¡Oh sí!, entre comillas por lo siguiente: probablemente en 4js el equipo que la generaba tenía esas ideas anti-documentación: nadie la lee, es para cobrar, la estamos agregando por compromiso.
La documentación de Genero 1.2 era bastante confusa. Solo algunos apartados tenían ejemplos, por demás, exageradamente simples (la típica calculadora con suma, resta, multiplicación y división de 2 números). No existía un índice o una forma de buscar de manera sencilla a través de actividades, por ejemplo: cómo abrir un archivo de texto. No existía un indice alfabético donde estuviera cada instrucción y hubo que leer prácticamente uno a uno los temas buscando si alguna de ellos decía algo referente a lo que necesitabamos.
Afortunadamente, hubo una mención tremendamente importante en la documentación, y era la confirmación de que el lenguaje de programacioón de Genero, llamado por el fabricante BDL, estaba basado enteramente en 4GL de Informix. Así que fuimos a la página web de Informix y ahí sí que encontramos una documentación abundante (y ejemplos) del lenguaje de programación. Lo siguiente fue ver cómo se mejoraba con Genero. Afortunadamente logramos sacar el proyecto dentro del tiempo estipulado y aprendimos a usar el producto.
Hoy día 4js Genero, aunque es un producto de nicho, se ha consolidado como una oferta estable e interesante. La documentación ha mejorado muchísimo, aunque aun hay apartados que no son claros, sobre todo los que refieren funcionalidades nuevas en cada versión que es liberada del producto.
Quiero enfatizar aquí que una documentación pobre, confusa, incompleta no es exclusiva de productos poco conocidos. Para nada. Espero que tengas la buenaventura de participar en numerosos proyectos y con variedad de tecnologías. Un día (quizás hoy después de leer esto) visita las páginas de documentación de Microsoft, IBM, Oracle, Amazon, etc. Compara simplemente la documentación de SQL Server, DB2 y Oracle, te vas a sorprender de las maravillas y las porquerías que encontrarás.
La conclusión de esta sección: nunca sabes quién usará tu producto, cómo, cuándo o dónde. Piensa en esa persona; considera que esa persona podrías ser tú. Quizás hayas hecho algún software o producto muy elaborado, una API, un Web service, una función… no importan las dimensiones, haz un esfuerzo por documentar y que quede claro qué y cómo funciona tu entregable.
Ahhhhh una cosa más antes de pasar con la siguiente sección. Respecto de esta pregunta y respuesta:
-¿Se pueden hacer formularios dinámicos como en PHP?
-No; te acabo de decir que no se interpreta. No; te acabo de decir que no se interpreta. La pantalla y la interacción con ella va compilada, no la puedes mover en tiempo de ejecución.
Sí logramos hacer formularios y pantallas dinámicas, nada más había que leer la documentación y no tener miedo.
Comenté al inicio de la crónica que he tardado en escribir esta tercera parte porque mis actividades profesionales se extendieron y tuve que hacer tiempos extras. Este comentario está alineado precisamente a cómo quiero cerrar la crónica y este tema de la documentación, pero para llegar a ese punto es necesario el contexto.
Después del proyecto en 2005 de la sección anterior, derivado de mis conocimientos de la plataforma Genero, he sido convocado a participar en otros proyectos en 2007, 2011, 2014 y 2020, donde la constante ha sido esa plataforma (reitero, es una solución de nicho, poca gente la conoce). Éste último ha consistido en coolaborar en el mantenimiento de un software que se hizo en el proyecto de 2011, justo el que ha incrementado mis actividades diarias.
En el proyecto de 2005, debido que eramos parte de un equipo más grande en el que estaría involucrado personal del cliente, y por consiguiente no seríamos responsables de todo el código, decidimos generar un estándar para documentar el código fuente; aunque cada quien se habría de encargar de funcionalidades específicas, teníamos que dejar alguna fuente de consulta para saber cómo modificar dicha funcionalidad si era necesario y quien la había hecho no estaba presente o no podía ejecutar el cambio por estar atareado con otras actividades.
Esa práctica la tomé y la he llevado conmigo desde entonces. De tal suerte que en pleno 2020 y 2021 me he encontrado con código fuente y los comentarios correspondientes de entregables que hice entre 2011 y 2014. Buena parte de lo que olvidé en el tiempo, lo pude retomar/recordar en poco tiempo, menos de una semana.
A inicios de Octubre de 2021 se planteó la liberación a producción de los componentes que he venido trabajando desde Octubre de 2020, prácticamente un año de trabajo. Solo trata de imaginar la cantidad de componentes que se liberaría. Una de las mayores complejidades de este proyecto radicaba en que los componentes que estaba modificando son componentes con una versión en productivo y que además de los cambios que yo realizaba en ellos, estos eran objeto de mantenimientos menores también.
Para mitigar la cantidad de trabajo que sería recopilar los cambios efectuados a estos, en un archivo aparte iba guardando cada cambio que hacía en base de datos, tablas nuevas, inserciones a catálogos, cambios en stored procedures y funciones. A su vez también llevaba un listado de los componentes que iba modificando…
Sin embargo, eventualmente me enfoqué en lo que estaba haciendo y el poderoso «lo anoto más tarde» hizo presa de mí. Evidentemente ese «más tarde» no llegó y ese futuro próximo se volvió problema de mi mismo del presente.
Para no prolongar más esta crónica, la documentación que puder haber ido recopilando día a día la tuve que hacer a marchas forzadas, extendiéndome en la noche, dos fines de semana y recorriendo programa por programa, identificando qué cambié y qué no. Esto tuve que hacerlo durante 6 semanas y contando además con el apoyo de una amiga; sin su ayuda francamente no habría podido culminar la recopilación de esta información a tiempo.
A veces el cliente de la documentación que no quieres hacer eres tú misma, ahórrate trabajo y documenta en tiempo.
Me di un balazo en el pie, es cierto; sin embargo, al ir recorriendo programa por programa generé una matriz de componentes, el diagrama de flujo de negocio y la relación en cada paso del negocio con los componentes que le dan solución, de forma que ahora todos esos componentes y sus dependencias, que no documenté en 2011 y tampoco documentaron de 2014 a 2020 ahora cuentan con documentos que explican qué son, donde están y qué hacen (además de los mencionados en el código fuente)…
Espero que con esta crónica logres apreciar el valor de la documentación, y que aunque parece un esfuerzo vano, de verdad vale la pena hacerlo. Piensa que en el peor de los casos, el principal afectado de la carencia de documentación serás tú. No te des un balazo en el pie y evítate desveladas y jornadas extra gratuitas.
Deja un comentario