Incorporando administrado repositorios de información para generar documentación on-demand
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Part Number | 29 | |
| Number of Parts | 173 | |
| Author | ||
| License | CC Attribution - NonCommercial - ShareAlike 3.0 Unported: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this | |
| Identifiers | 10.5446/20224 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language | ||
| Production Place | Bilbao, Euskadi, Spain |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
| |
| Keywords |
EuroPython 201529 / 173
5
6
7
9
21
27
30
32
36
37
41
43
44
45
47
51
52
54
55
58
63
66
67
68
69
72
74
75
77
79
82
89
92
93
96
97
98
99
101
104
108
111
112
119
121
122
123
131
134
137
138
139
150
160
165
167
173
00:00
InformationSystem administratorWeb pageRepository (publishing)Lecture/Conference
00:29
Physical systemMultiplication sign
00:55
XMLUML
01:20
InformationWordRepository (publishing)Computer animation
02:02
InformationBitRevision controlWordComputer fileMultiplication signRepository (publishing)Program flowchart
02:33
CodeInformationMathematicsType theoryIncidence algebraControl systemCausalityPhysical systemProjective planeRevision controlCartesian coordinate systemLattice (order)Source codeComputer fileClient (computing)TrailComputer animationProgram flowchart
05:58
CodeInformationIncidence algebraSoftware testingTask (computing)Probability density functionFunctional (mathematics)Physical systemProjective planeRevision controlCASE <Informatik>Social classWordWeb pageSource codeComputer fileClient (computing)Computer animation
09:35
CodeInformationIncidence algebraPoint (geometry)PlastikkarteTrailWikiDiagramComputer animation
10:30
Incidence algebraComputer fileTrailWebsiteDifferent (Kate Ryan album)Multiplication signWikiComputer animation
11:07
CodeImplementationCombinational logicPhysical systemSoftware bugWikiRight angleComputer animation
12:06
CodeBitPresentation of a groupEndliche ModelltheorieComputer animation
12:34
RoutingCodeFunctional (mathematics)Mobile appComputer animation
13:17
CodeSoftware frameworkComputer animation
13:50
CodeVariable (mathematics)Functional (mathematics)Projective planeRoutingCartesian coordinate systemComputer animation
14:30
Computer animation
14:57
CodeInformationIncidence algebraPhysical systemProjective planeElectronic mailing listTrailWikiXML
15:47
CodeInformationMathematicsSemiconductor memoryIncidence algebraTask (computing)Sheaf (mathematics)Physical systemProjective planeConfiguration spaceInternetworkingWeb pageCartesian coordinate systemClient (computing)TrailMultiplication signWikiRepository (publishing)
19:01
Medical imagingProjective planeComputer animation
20:22
CodeInformationComputer clusterFunction (mathematics)SI-EinheitenUniqueness quantificationContent (media)Physical systemProjective planePresentation of a groupPoint (geometry)outputWordWeb pageFile formatReflection (mathematics)Computer fileClient (computing)View (database)WebsiteDifferent (Kate Ryan album)Single-precision floating-point formatWritingWikiWeb 2.0Repository (publishing)Software developerComputer animation
Transcript: Spanish(auto-generated)
00:02
Entonces, gracias por venir. Específicamente, hablo de incorporando administrados repositorios de información para generar documentación on demand. Y la próxima página fue un
00:21
requerimiento del departamento legal, entonces, va a ser muy rápido. Ok, entonces, ¿qué haces con un problema como documentación? Tenemos un problema con documentación. Muchas veces no lo hacemos o no está actualizado. Entonces,
00:43
esta documentación causa confusión y problemas en un proyecto y tenemos que hacer algo porque estamos haciendo ahorita no está funcionando. Entonces, por fin de la presentación, voy a usar, bueno, dar un ejemplo de código de un sistema que uso y ahí se puede bajar
01:10
lo de aquí. Entonces, la documentación. En la manera de pienso documentación, hay artefactos de documentación. ¿Y qué son esos artefactos? Esos artefactos son los
01:26
archivos de Word, son los archivos de Markdown o PDF o HTML o PowerPoint. He recibido documentación en PowerPoint de requerimientos y no me gusta usar PowerPoint. Si alguien en su
01:49
PowerPoint para documentar los requerimientos, tenemos que hablar con esta persona. Entonces, todos esos artefactos que son, son nuestros repositorios de información y esos repositorios
02:07
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 es, bueno, creamos repositorios
02:21
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
02:42
de Word, todos estos artefactos causan confusión para el equipo, para el cliente, para los managers, para la persona que está leyendo, bueno, no leyendo, guiando el proyecto. Hay confusión por todos. Entonces, en estos repositorios de información,
03:04
esos 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,
03:27
cosas que parecen que son fáciles, pero esa información cambia durante un proyecto. Entonces, si no tenemos esta información actualizada, otra vez va a causar confusión.
03:43
Necesitamos una definición del éxito, diseños del proyecto. Y de las fuentes, tenemos el sistema de rastreo de incidencias, puede ser un fuente, puede ser el código, puede ser una wiki o también las reuniones con el equipo. Y todos estos tipos y fuentes
04:05
de información son importantes 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.
04:27
Es el nombre del proyecto, el tipo de documento, con la fecha en que este documento se empezó. Y bueno, hicimos una revisión, entonces tenemos esto, pero se revisó un segundo,
04:42
y yo lo hizo. Pero ahora es final, ya final, con corregido, pero ya final. Y esta es la versión que entregamos al cliente. ¿Cuántos han visto nombres de archivos así? Siempre, siempre. Entonces, este tipo de control de versiones de nuestra documentación,
05:11
otra vez causa confusión y nos va a dar problemas. Si queremos algo que sea útil, tiene que ser utilizado. Y qué significó en eso es, es algo que queremos es la información.
05:29
No queremos documentos, queremos información. Y la información, si queremos que esta información sea útil, tenemos que usarlo. Entonces, esta información tiene que estar
05:42
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 esta documentación. Hay Sphinx, EpiDoc, Docsagen, PDoc. Esas herramientas se puede documentar su código
06:04
ahí adentro del código, donde está trabajando con el código. Entonces, si hacemos un clas en Python, podemos poner la documentación de este clas en el comentario del código. Y si cambiamos el código, podemos tener, bueno, hay funciones ahí en Sphinx, no sé
06:25
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 compile el código, va a hacer las pruebas
06:41
cuando compila. Y si falla los tests ahí en el comentario, va a fallar el compila. Entonces, sabe que, oh, 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
07:07
está ahí donde está trabajando. Y he visto en mi trabajo con los equipos con quienes trabajo yo que si no es fácil, si la información no está donde están
07:22
trabajando, no lo va a actualizar, nunca. Y también si hay muchos artefactos que tenemos, no vamos a actualizar estos artefactos. Oh, si lo actualizamos, el cliente va a tener una versión y el equipo tiene otro. Entonces, en este, ¿qué versión define
07:46
el éxito? ¿Qué vamos a hacer? Porque nuestro cliente piensa que, oh, el proyecto va a ser sí y el equipo dice, oh, pero no puede ser sí porque tenemos esto y eso y eso y eso. Entonces, vamos a cambiarlo y vamos a actualizar la
08:03
documentación por nuestro equipo, pero no la demos al cliente. Entonces, a lo menos tenemos que tener y, bueno, a lo menos tenemos que hablar con nuestro cliente y a lo peor, puedo ser bien malo. Entonces, tenemos que
08:26
tener un solo fuente para generar artefactos para el consumo de la información. En vez del cliente, el cliente no tiene que saber todos
08:43
de los datos del proyecto que está en el sistema de estrella de incidencias, no tiene que saber todos los páginas de un wiki, pero lo que necesitan ellos para entender es un solo fuente, un artefacto que siempre está actualizado. Y si tiene un PDF que está viejo, este PDF
09:09
debe tener el lugar donde se puede ir para bajar una versión actualizada.
09:20
Y otra vez queremos mantener la información donde está trabajando y donde van los ingenieros para requerimientos o tareas. Y en los equipos míos no van a archivos de Word, nunca, nunca. Usualmente usamos cosas
09:44
como el rastreo de incidencias para poner los requerimientos allí 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
10:05
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.
10:27
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
10:41
diferentes, no me gusta, no me gusta. Entonces tengo un interno allí en donde trabajo en que ya no usamos archivos de Word para esta documentación. Nosotros usamos el rastreo de incidencias para los requerimientos y
11:05
la wiki para los narrativos datos. Entonces eso es lo que decimos, sí, los requerimientos son las tres. Y así, usamos fog bugs. Entonces esos
11:22
ejemplos van a usar fog bugs, pero los principios son lo mismo. Sin, bueno, no importa qué sistema usa, se puede usar los principios. He hecho esto con JIRA y Confluence, pero bueno, la implementación no fue
11:44
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, otras, son las páginas de la wiki. Y para
12:06
combinar 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
12:22
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 Hola Mundo. Entonces para este ejemplo hay dos routes y voy a
12:46
definir ahí con app.route y éste va a localhost. Y el código de éste es todo el código. El app.route es de decorator. Éste define que la función
13:07
Hola va a ajustar 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
13:36
vamos acá. Ahí, Hola Mundo. Y es muy fácil para usar Flask. Es micro
13:43
framework. Y el código para eso solo es sí. Y éste es todo. Éste es todo el código para esta aplicación. Y el otro es este route. Entonces vamos a tener un
14:02
proyecto y éste es el variable de proyecto y define que cuando ajustamos esta función que pasamos este variable a la función. Entonces sí. Vamos allí. Ahí está. Fácil. Entonces ok. Ahí está. Ok. Entonces tenemos así.
14:55
Hablé de esto y esto y esto. Y ahora el código. Entonces estos principios de
15:01
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 qué vamos a hacer. Vamos a usar Flask para bajar la información y mostrar un lista de los proyectos. Y cuando vamos
15:26
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.
16:02
Entonces éste es vivo. Funciona. Estoy usando un repositorio, un sistema de rastreo que está en el internet. Y cuando voy a este proyecto, a este doctor, entonces está bajando toda la información que necesita.
16:26
No hay un repositorio allí con esta aplicación porque todo esta información está en memoria, está en el cliente. Y hice esto porque quiero que esta información siempre
16:41
está actualizado de qué está en la sistema de rastreo de incidencias y en la wiki. Si algo cambia aquí, debe cambiar. Bueno, vamos a hacer esto. Pero una vez. Entonces en el código
17:03
tenemos esto, que es nuestra aplicación de Flask. Y tenemos dos routes. Y en el primero necesitamos un list de proyectos. Y uso este código para conseguir esto.
17:22
Entonces solo necesito el proyecto, un ID, a la persona que está en cargo del proyecto. Y esa información de este proyecto. Y cuando tengo esto y alguien va a este
17:46
proyecto, a este lugar en la aplicación, entonces necesitamos información de los tareas también de los wikis. Y otra vez uso eso para hacer esto. Los requerimientos aquí.
18:04
Y necesito esta información para mostrarlo en el web. Y también la información de la wiki. Y tengo esta configuración en la cual se puede definir que secciones de la wiki quiere mostrar.
18:24
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 aquí está.
19:02
A Lore Mipsum. Más que nada porque no te da la imagen de cómo de verdad suelen ser cosas en realidad. Digo, a lo mejor si tienes un proyecto que puedes enseñar vivo tuyo, un público, para ver cómo es esto en realidad. ¿Cómo se cambia? No, no sé cómo se cambia, sino cómo es un hecho con esto.
19:27
Sí, porque eso es Lore Mipsum. Exactamente, porque es Lore Mipsum y como que muy bien, tres títulos, pero... Debo... ahorita no, porque el equipo... uso esto en mi equipo y el equipo nada está público.
19:43
Entonces... Yo solo le cuento si por si acaso tengas una cosa que sea pública para verlo en... Voy a hacer esto. Sí, los puedes pasar a ver. Sí, voy a hacer esto. Funcionando. Sí, voy a hacer esto para que todos puedan ver cómo funciona y cómo va a aparecer.
20:05
Para ver si sea útil para su equipo. Exactamente. Gracias. Otras preguntas. Porque, bueno, explicó muy básicamente el código, entonces si hay más preguntas
20:33
puedo explicar más, pero por eso es más o menos todo. Lo importante para mí por esta presentación
20:42
son los principios de cómo pensamos en documentación, cómo pensamos de dónde vamos a poner la información y dónde está esta información que sea útil para la persona que está usando un sistema así.
21:01
Y en nuestros equipos, cómo vamos a tener una antena donde todos estamos escribiendo esta información y actualizando la documentación. Pero sí, hay preguntas.
21:21
Yo tengo una pregunta, bueno, igual es más una reflexión o cómo o qué opinas sobre un tema. Yo soy un true believer 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 tienen una manía
21:44
por la documentación como bastante... Aunque a veces, aunque esa documentación no se la acabe leyendo a nadie pero necesitan tener un documento Word que explique esto y tal. Yo considero que para el equipo de desarrollo depende de los proyectos, startups y demás,
22:01
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 y sabes que tu equipo de desarrollo 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
22:23
única y exclusivamente a la documentación, entonces era para saber qué opinas o si has tenido algún ejemplo alguna vez. Sí, lo mismo. Donde trabajo yo estoy trabajando con el gobierno, entonces ellos no van a usar un wiki, necesitan un archivo. No ha sucedido nada sin ese archivo, entonces necesitamos esto.
22:46
Pero todavía usamos este sistema en nuestro interno y por eso, ¿qué hago yo? Pongo un pedazo de información de este documento no está actualizado ahora.
23:04
Entonces, si quieres saber lo más actualizado está aquí y pongo un lugar donde está y se puede ir a ese lugar para bajar un nuevo archivo. Entonces, siempre usamos el Jenkins para crear esas documentaciones en la misma manera que lo hacemos con nuestro código.
23:35
No podemos hablar de eso ahorita, pero entonces, ¿cómo se dice como un disclaimer?
23:51
No sé, bueno, un aviso. Pongo un aviso en el documento que explica que este documento fue generado por este sistema
24:05
y la información actualizada está aquí. No hay una solución perfecta, pero es lo que hacemos nosotros.
24:28
Siempre, siempre. No escribimos, no creo un archivo de Word de mano, nunca. Uso cosas como Pandoc. Es una herramienta que se puede usar con archivos de Word, Markdown, HTML, todos los formatos
24:56
y se puede cambiarlo en otros formatos. Entonces, se puede tener un Word y después tener un HTML.
25:04
O se puede tener 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
25:22
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.
25:42
¿Qué es lo que solicitan los clientes en la documentación? ¿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?
26:03
¿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,
26:29
qué es la definición del éxito por el proyecto. Entonces, tenemos que hacer esto y eso y eso, pero estas cosas no tenemos que hacer
26:40
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.
27:02
Cosas así es lo que pongo aquí y también este es bueno 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
27:26
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í,
27:41
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.
28:01
Necesita una cosa, un artefacto que contiene todos esos repositorios diferentes. Vale, gracias. ¿Alguna pregunta más?
28:26
Yo no tengo mucha experiencia, no me queda muy claro, solo un poquito la idea. He entendido la salida de datos y que los datos estén centralizados, pero en sí como es la entrada de datos, siempre se hace a través, bueno entiendo la modificación,
28:46
pero la entrada de datos siempre es el sistema, cambiar los repositorios. Entonces la pregunta es, aún con eso siempre tiene que escribir los datos, entonces tiene
29:00
que escribirlo con archivos normales y tiene que usar ese sistema, tiene que escribirlo. ¿Es lo que está diciendo? Entonces sí, siempre tenemos 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
29:28
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?
29:44
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
30:03
un lugar donde aquí es el resumen para este proyecto y solo vamos a actualizar este resumen y después todos estos documentos, cuando cambio este resumen, van a actualizar
30:20
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.
30:45
Vale, pues muchas gracias, Todd. Gracias.