 Entonces, gracias por venir. Específicamente, hablo de incorporando administrado repositorios de información para generar documentación on demand. Y la próxima página fue un requerimiento del departamento legal, entonces, va a ser muy rápido. OK, entonces, ¿qué haces con un problema como en documentación? Tenemos un problema con documentación. Muchas veces no lo hacemos o no está actualizada. Entonces, esta documentación causa confusión y problemas en un proyecto y tenemos que hacer algo porque que estamos haciendo ahorita no está funcionando. Entonces, por fin del presentación, voy a dar un ejemplo de un código de un sistema que uso. Y ahí se puede bajarlo de aquí. Entonces, la documentación, en la manera de pienso documentación, yo hay artefactos de documentación y ¿qué son estos artefactos? Estos artefactos son los archivos de Word. Son los archivos de Markdown o PDF o HTML o un PowerPoint. He recibido documentación en PowerPoint de requerimientos y no me gusta usar PowerPoints. Si alguien en su equipo está usando PowerPoint para documentar los requerimientos, tenemos que hablar con esta persona. Entonces, todos esos artefactos que son nuestros repositorios de información y esos repositorios de información son la documentación. La problema que usando artefactos como archivos de Word, como nuestra documentación, es que toda la información creamos repositorios de información nuevos cada vez que creamos un documento, una versión de un documento. Entonces, bueno, vamos a hablar de eso un poquito. Y si no tenemos cuidado, esos artefactos, que tenemos muchos artefactos o tres versiones de un documento en un archivo de Word, todos estos artefactos causan confusión para el equipo, para el cliente, para los manager, para la persona que está leyendo, bueno, no leyendo, guiando el proyecto. Hay confusión por todos. Entonces, en estos repositorios de información, estos artefactos de documentación, ¿qué son los tipos y los fuentes de información? Necesitamos los datos del proyecto, el nombre del proyecto, ¿qué vamos a hacer? Los requerimientos para cómo la aplicación va a funcionar. También los puntos del contacto, cosas que parecen que son fácil, pero esa información cambia durante un proyecto. Entonces, si no tenemos esta información actualizada, otra vez va a causar confusión. Necesitamos un definición del éxito, de los diseños del proyecto. Y de las fuentes, tenemos el sistema de arrastreo de incidencias, puede ser un fuente, puede ser el código, puede ser una wiki o también los reuniones con el equipo. Y todos estos tipos y fuentes de información son importante tener en nuestra documentación. Pero otra vez, hablamos de versiones de nuestra documentación. Muchas veces, la sistema de control de versiones de nuestros documentos es así. Tenemos un archivo, y este archivo tiene un nombre. Es el nombre del proyecto, que el tipo de documento con la fecha en que este documento se empezó. Y, bueno, hicimos una revisión. Entonces, tenemos esto, pero eso se revisió un segundo y yo lo hizo. Pero ahora es final, ya final, con corregido, pero ya final. Y este es la versión que entregamos a la cliente. Cuando se han visto nombres de archivos, así. Siempre, siempre. Y entonces, este tipo de control de versiones de nuestra documentación otra vez causa confusión. Nos va a dar problemas. Si queremos algo que sea útil, tiene que ser utilizado. Y qué significa en eso es el algo que queremos es la información. No queremos documentos. Queremos información. Y la información, si queremos que esa información sea útil, tenemos que usarlo. Entonces, esa información tiene que estar en un lugar donde vamos a trabajar con esta información. Un ejemplo es el código. Y documentación para el código. Hay muchas herramientas para este documentación. Hay Sphinx, Epidoc, Doxygen, Pidoc. Esos herramientos se pueden documentar a su código ahí adentro del código, donde está trabajando con el código. Entonces, si hacemos un class en Python, podemos poner la documentación de este class en el comentario del código. Y si cambiamos el código, podemos tener, bueno, hay funciones ahí en Sphinx. No sé, de los otros, pero en Sphinx, cuando compila el código, puede poner los tests, las pruebas para el código ahí en el comentario. Y cuando compila el código, va a ser las pruebas cuando compila. Y si falla los tests ahí en el comentario, va a fallar el compila. Entonces, sabe que necesito actualizar la documentación ahí adentro del comentario. Y para el ingeniero que está haciendo el código, es muy fácil porque la documentación está ahí donde está trabajando. He visto en mi trabajo con los equipos con quienes ha trabajo yo que si no es fácil, si la información no está donde están trabajando, no lo va a actualizar nunca. Y también si hay muchos artefactos que tenemos, no vamos a actualizar estos artefactos. Si lo actualizamos, el cliente va a tener una versión y el equipo tiene otro. Entonces, en este, ¿qué versión define el éxito? ¿Qué vamos a hacer? Porque nuestro cliente piensa que el proyecto va a hacer, sí, y el equipo dice, oh, pero no puede hacer, sí. Porque tenemos esto, y eso, y eso, y eso. Entonces, vamos a cambiarlo y vamos a actualizar la documentación por nuestro equipo. Pero no la demos al cliente. Entonces, a lo menos tenemos que hablar con nuestro cliente y a lo peor, puede ser, bien malo. Entonces, tenemos que mantener un solo fuente para generar artefactos para el consumo de la información. En el vez del cliente, el cliente no tiene que saber todos de los datos del proyecto que está en el sistema de estreo de incidencias. No tiene que saber todos los páginas de uno wiki. Pero qué necesitan ellos para entender es un solo fuente, un artefacto que siempre está actualizado. Y si tiene un PDF que está viejo, este PDF debe tener el lugar donde se puede ir para bajar una versión actualizada. Y otra vez, queremos mantener la información donde está trabajando y dónde van los ingenieros para requerimientos o tareas. Y en los equipos míos, no van al archivos de Word, nunca, nunca. Normalmente usamos cosas como el rastreo de incidencias para poner los requerimientos ahí o tarjetas, como agile, los historias. O tal vez, a veces, uno wiki. Y uno wiki puede tener información de como los puntos de contacto o una resumen del proyecto, una definición del éxito. Y aquí en la wiki es la información que, bueno, digo yo, los datos narrativos de un proyecto. Y estos datos son importantes como la información del código es importante. Y, bueno, la cosa que quiero yo, que yo solo quiero escribir una vez. Si tengo que escribir la misma cosa, tres veces en repositorios diferentes, no me gusta. No me gusta. Entonces, tengo uno en Terno ahí donde trabajo en que ya no usamos archivos de Word para esta documentación. Nosotros usamos el rastreo de incidencias para los requerimientos y la wiki para los narrativos datos. Entonces, eso es lo que hicimos. Los requerimientos son las tres. Y así usamos fogbugs. Entonces, esos ejemplos va a usar fogbugs, pero los principios son lo mismo. Sin, bueno, no importa qué sistema usa, se puede usar los principios. He hecho esto con Gira y Confluence, pero, bueno, la implementación no fue bueno. Entonces, no lo tengo en código ahorita. Pero aquí tenemos los requerimientos. Puedes ver estos ahí con el llave. Son mis requerimientos. Y esos datos narrativos, otra vez, son los páginas de la wiki. Y para caminar todo junto, uso flask y Python. ¿Cuántas personas usan flask o sabe cómo usar flask? OK, entonces, voy a hablar un poquito de flask para entender el código que voy a mostrar. Entonces, con flask hay rutas, routes, lógica de negocios y los modelos de presentación. Entonces, hizo un flask o la mundo. Entonces, para esto, ejemplo, hay dos routes. Y voy a explicarlos. El primero, lo definimos ahí con app.route. Y este va a localhost. Y ese es todo el código. El app.route es de decorator. Este defiende que la función hola va a ejecutir cuando vamos a ese lugar. Entonces, podemos ir y vamos a ver eso y voy a mostrar. Entonces, ahí está toda la aplicación ahí. Y si vamos acá, ahí, hola mundo. Y es muy fácil para usar flask. Es micro framework. Y el código para eso solo es sí. Y ese es todo. Ese es todo el código para esta aplicación. Y el otro es ese route. Entonces, vamos a tener un proyecto. Y este es el variable de proyecto. Y defiende que cuando ejecutimos esta función, que pasamos este variable a la función. Entonces, sí. Vamos ahí. Ahí está. Fácil. Entonces, OK. Ahí está. OK. Entonces, tenemos, sí, hablé de esto y esto y esto. Y ahora el código. Entonces, esos principios de flask son lo mismo. Entonces, voy a hablar de cómo hizo el código. Y otra vez se puede ir aquí para bajarlo. Y que vamos a hacer, vamos a usar flask para bajar la información y mostrar un lista de los proyectos. Y cuando vamos a un proyecto, vamos a bajar la información de las wikis y también de los requerimientos dentro de la sistema de rastreo de incidencias. Entonces, aquí, sí, aquí funciona. Entonces, ese es vivo. Es funciona. Ahí. Este es, estoy usando un repositor en un sistema de rastreo que está en el internet. Y cuando voy a este proyecto, este doctor, entonces, está bajando toda la información que necesita. No hay un repositorio ahí con esa aplicación porque toda esa información está en memoria, está en el cliente. Y hizo esto porque quiero que esa información siempre está actualizada de que está en la sistema de rastreo de incidencias y en la wiki. Si algo cambia aquí, debe cambiar. Bueno, puedo hacer esto, pero una vez. Entonces, en el código tenemos esto, que es nuestra aplicación de flask. Y tenemos dos rounds. Y en el primero, necesitamos un liste de proyectos y uso este código para conseguir esto. Entonces, solo necesito el proyecto, un ID a la persona que está en cargo del proyecto. OK. Que está en carga, al cargo. Y esa información de este proyecto. Y cuando tengo esto y alguien va a este proyecto a este lugar en la aplicación, entonces necesitamos información de los tareas y también de los wikis. Y otra vez uso eso para hacer esto, los requerimientos aquí. Y necesito esa información para mostrarlo ahí en el web y también la información de la wiki. Y tengo esta configuración en lo cual se puede definir cuál secciones de la wiki quiere mostrar. Porque muchas veces tenemos muchas páginas de una wiki que no necesitamos mostrar en cada documento que tenemos. Entonces, se puede definir esto aquí en esta configuración. Y sí, y aquí está. A Lorem Ipsum, más que nada, porque no te da la imagen de cómo de verdad suelen ser cosas en realidad, ¿no? Digo, a lo mejor si tienes un proyecto que puedes enseñar vivo tuyo, público, para ver cómo es esto en realidad. ¿Cómo se cambia? Si cambió algo. No sé cómo se cambia, sino cómo es un hecho con esto. Sí, porque eso es Lorem Ipsum. Exactamente, porque es Lorem Ipsum y como que muy bien, tres títulos, pero. Debo ahorita no, porque el equipo uso eso en mi equipo y el equipo nada está público. Entonces, ah. Yo te pregunto si por si acaso tengas una cosa que sea pública para verlo en. Voy a hacer esto. ¿Puedes pasar? Sí, voy a hacer esto. Funcionando. Sí, voy a hacer esto para que todos pueden ver cómo funciona y cómo va a aparecer para ver si sea útil para su equipo. Exactamente. Proyectos. Gracias. Otras preguntas. Porque, bueno, así, explicó muy básicamente el código. Entonces, sí, hay más preguntas. Puedo explicar más, pero por eso es más o menos todo. Lo importante para mí por esta presentación son los principios de cómo pensamos en documentación. ¿Cómo pensamos de cómo vamos a, bueno, dónde vamos a poner la información? ¿Y dónde está esa información que sea útil para la persona que está usando un sistema así? Y en nuestros equipos, ¿cómo vamos a tener un enteno donde todos estamos escribiendo esa información y actualizando la documentación? Pero sí, hay preguntas. Yo tengo una pregunta. Bueno, igual es más una reflexión o qué opinas sobre un tema. Yo soy un truvelíver de que tiene que haber un único punto de información y que solo se modifica ahí, porque si no no tiene ningún sentido y no acabas actualizando, entonces acaba todo desactualizado y demás. Lo que pasa es que sí que he trabajado a veces con grandes corporaciones en las que pues tienen una manía de documentación como bastante. Aunque a veces, aunque esa documentación no se la cabe leyendo a nadie, pero necesitan tener un documento Word que explique esto y tal. Entonces, yo considero que para el equipo de desarrollo, depende de los proyectos, startups y demás, wikis, web y demás funciona muy bien. Pero cuál es tu punto de vista cuando estos clientes o estas corporaciones requieren esos documentos, sabes que tu equipo de desarrollo pues al final va a estar trabajando en la wiki y va a acabar de. Entonces, yo lo único que he visto que ha funcionado en algún proyecto es tener alguien dedicado única y exclusivamente a la documentación. Entonces, era para saber si qué opinas o si has tenido algún ejemplo alguna vez. Sí, lo mismo. ¿Dónde trabajo yo estoy trabajando con el gobierno? Entonces, si ellos no van a usar un wiki, necesitan un archivo. No ha sucedido nada sin ese archivo. Entonces, necesitamos esto. Pero todavía usamos este sistema en nuestro interno. Y por eso que hago yo pongo un pedazo de información de este documento no está actualizado ahora. Si quieres saber lo más actualizado está aquí y pongo un lugar donde está y se puede ir a ese lugar para bajar una nueva archivo. Entonces, siempre usamos el Jenkins para crear estos documentaciones con nuestro en la misma manera que lo hacemos con nuestro código. Entonces, y bueno, no podemos hablar de eso ahorita. Pero entonces, ¿cómo se dice como un disclaimer? No sé, bueno, un warning, un aviso, un aviso. Pongo un aviso en el documento que explica este documento fue generado por este sistema y la información actualizada está aquí. No hay una solución perfecta, pero es lo que hacemos nosotros. Siempre, siempre. No escribimos, no creo un archivo de word de mano. Nunca. Uso cosas como Pandoc. Ha escuchado de Pandoc. Es una herramienta que se puede usar con archivos de word, markdown, HTML, todos los formatos y se puede cambiarlo en otros formatos. Entonces, se puede tener un word y después tener un HTML. Se puede tener a markdown y después tener un archivo de word. Entonces, uso eso para generar artefactos diferentes. Y esos artefactos es que pongo en el website y se puede ir a ese lugar para bajarlo, lo más actualizado. Gracias. Otras. Alguna pregunta más? Me gustaría saber a mí qué documentación normalmente se entrega a los clientes. ¿Qué es lo que solicitan los clientes en la documentación? Entonces, lo siento. ¿Qué información se entrega a los clientes de documentación? La información está entregada a los clientes. ¿Qué es lo que se indica en esa documentación? ¿Qué quieren saber de la documentación de los clientes? El contenido de esa documentación. Para los clientes, el contenido de documentación, usualmente es un resumen de qué vamos a hacer a los requerimientos, qué son los requerimientos específicamente para la aplicación, el proyecto. ¿Qué es la definición del éxito por el proyecto? Entonces, tenemos que hacer eso y eso y eso. Pero estas cosas no tenemos que hacer porque no podemos hacerlo en este tiempo o en este proyecto. Y también, a veces, pongo un diccionario para explicar cuando yo digo esta palabra, este es lo que significa en este sentido, en este proyecto. Las cosas así es lo que pongo aquí. Y también este es bueno para, no solamente para los clientes que tienen que firmar y decir, sí, es lo que dijo que quiero que haga usted. También es para miembros del equipo que son nuevos y están empezando en un proyecto y puede dar a ellos. Lea la documentación y ahí está, ¿qué estamos haciendo? Y pueden verlo y consumirlo en un artefacto todo en vez de leer una página aquí, página aquí, página aquí. Todas las páginas de Wiki y los requerimientos son buenos para actualizar y mantener la información. Pero para leerlo y consumir la información no es muy fácil de tener. Todos esos repositorios pequeños necesitan una cosa, un artefacto que contiene todos estos repositorios diferentes. Vale, gracias. OK. ¿Pero alguna pregunta más? Bueno, yo no tengo mucha experiencia. No me queda muy claro si solo un poquito y la idea. He entendido la salida de datos y que los datos estén centralizados, pero en sí. ¿Cómo es la entrada de datos? Es siempre, se hace otra vez, bueno, que entiendo la modificación, pero la entrada de datos siempre es al sistema cambiarlo en repositorio. Entonces la pregunta es, aún con eso, siempre tiene que escribir los datos. Entonces, tiene que escribirlo con archivos normal y tiene que usar ese sistema tiene que escribirlo. ¿Es lo que está diciendo? Entonces, sí. Siempre tendemos que escribir la información, pero con esto podemos escribirlo una vez, en un lugar que otra problema que tenía que, bueno, tenemos un resumen de un proyecto y tengo que usar ese resumen en dos documentos. Entonces, ¿por qué tengo que escribirlo aquí y después moverlo, mudarlo acá para otro documento? Entonces, tengo dos documentos diferentes de temas diferentes, pero los dos tienen ese resumen. Y si cambio uno, tengo que actualizar la otra. Entonces, sí, puedo tener un lugar donde aquí es el resumen para este proyecto y solo vamos a actualizar ese resumen. Y después, todos estos documentos, cuando cambio este resumen, van a actualizar con el resumen correcto, en vez de tengo que actualizar aquí, aquí, aquí, aquí, solo tengo que actualizar en un lugar. Pero sí, siempre tenemos que escribirlo, pero, ojalá, que solo estamos escribiendo una vez, en vez de muchas veces. Vale, pues muchas gracias, todo. OK, gracias.