Saludos de nuevo, volvemos de nuevo al blog después de una larga temporada de letargo. Espero que entre post y el siguiente el intervalo no sea tan largo. ¡Venga!, al grano:

Uno de los aspectos que siempre me ha preocupado ha sido el que cualquier aplicación, web, base de datos, temas en los que yo esté implicado, etc. quede bien documentada para las “generaciones futuras”.  Aunque si soy sincero, en realidad es que las personas de tu equipo lo dejen bien documentado por si tengo que enfrentarme al producto y resulte que mi conocimiento sobre cómo está hecho sea limitado.

Eso lo ha sufrido en sus carnes el amigo David Maniega durante los años que trabajamos juntos: David como webmaster y desarrollador cerraba un proyecto y con la presión ya se metía en otro. Yo le insistía en que debía documentarlo todo por si en su ausencia debía enfrentarme a todo eso que desarrollaba. Bien, en realidad se lo decía de modo más coloquial: que si lo atropellaba un autobús yo que quedaba “colgado” con la aplicación.  Aunque debo reconocer que con el tiempo me familiaricé con su modo de trabajar y sin documentación podía deducir porqué lo había hecho de un modo y no de otro 😉

Volviendo al tema de este post: Unos días antes de cerrar el 2015 asistí a un interesante curso sobre Arquitectura REST y APis, pero tranquil@s, no voy a disertar sobre conceptos marcianos, ni REST ni APIs, no sufran.

Imagen: Pixabay  CCO Public Domain

Pero en las conclusiones, Alex Muntada que impartía el curso apuntaba que la peor pesadilla sobre las API y el diseño de una API REST era la documentación: que en general es mala, obsoleta, errónea o inexistente.  Y gracias a esto descubro el concepto de “Semantic Gap”, que tal como lo describe Wikipedia hace referencia a la diferencia entre lo que se describe y lo que se interpreta al utilizar “lenguajes” distintos.

Y salvando las distancias entre este concepto tecnológico y llevándolo a nuestro terreno, me atrevo a afirmar que esto también nos sucede a nosotros. Imaginémonos el siguiente caso:

• El equipo TIC, desarrolla una aplicación que debe ser administrada por nosotros y utilizada por nuestros usuarios
• La documentación –y los comentarios dentro del código– estarán probablemente redactados en un lenguaje “marciano” para la mayoría de nosotros pero entendible para los miembros del equipo TIC.
• Y si los desarrolladores elaboran la documentación para el administrador de la aplicación y para el usuario final, lo más probable es que suceda algo similar: en un lenguaje no tan “marciano”, pero probablemente de difícil comprensión.
• Seguramente el administrador de la aplicación realizará el esfuerzo en familiarizarse con ella y acabe descubriendo todas las prestaciones de esta. Pero ¿Y si cambiamos al administrador? …. pues volver a empezar de nuevo hasta tomarle de nuevo el pulso.
• Lo peor estaría en el lado del usuario: Ese fantástico –y a veces demasiado extenso–tutorial que ha costado tanto esfuerzo ¿Está pensado para ellos? ¿Se utilizó la terminología que ellos entienden? Atent@s que aquí puede hallarse el éxito o fracaso de una aplicación y también de un servicio, protocolo, etc.

Como ejemplo “la aplicación tiene un “cron” que cada noche lanza una “query” que llama a una “vista” que se llama “Importpatron””.

Si no estamos familiarizados con el tema de servidores eso de “cron” no lo asociaremos a una “tarea programada”, según nuestros conocimiento con el diseño de bases de datos quizás desconozcamos que “query” se refiere a una consulta y que “vista” es una tabla creada a partir de consultar diferentes tablas (¿Tablas?, ¿Qué son tablas? 😉 )  y quizás sí que interpretamos lo de  “importpatron” que deben ser los datos de usuarios importados de otro sistema de información, aunque quizás otro TIC no entienda en concepto ”patron” al que muy probablemente estemos familiarizados los que gestionamos sistemas de gestión bibliotecaria.

Vamos, todo un tema que se podría traducir para el administrador por  “La información de los usuarios es importada cada noche de la base de datos ….. que gestiona el Servicio ….. ” y quizás para el usuario como “La información se actualiza diariamente a las … horas”.

El ejemplo lo he centrado en el entorno TIC, pero si eres TIC no te ofendas, es tan solo un ejemplo. Hace poco encontré  un manual que hice hace casi 10 años sobre cómo realizar el inventario en mi lugar de trabajo y si los que realizan dicha tarea lo entendieron a la primera, se merecen un homenaje.

Me imagino que para minimizar el “gap”  –que no resolverlo– debemos trabajar de modo transversal e interdisciplinar y además de realizar el esfuerzo de ponerse en la “piel” del destinatario y sin olvidar que cuando mejoramos la aplicación, desarrollamos una nueva versión o simples cambios menores deberemos revisar la documentación ya que lo ms probable es que requiera algunos cambios.

Pues,  ¡ya tenemos un nuevo propósito para 2016! 😉

Bien, ya sabéis, cualquier comentario, aportación y mejora de esta entrada será bienvenida. Un poco de “scroll”, y  más abajo tenéis la oportunidad de hacerlo (¿Scroll?, ¿Qué es scroll? 😉

PD: Algun@s sabéis que otra de las cosas que me preocupan es tener que hacer las cosas dos veces, vamos que si la información ya está disponible en un sitio, no volver a entrarla o duplicarla. Si también os preocupa, entonces “rascar” un poco en el tema de Arquitectura REST y APIs, vuestros bibliotecarios y usuarios os lo agradecerán.