¿PODRÍAN COEXISTIR LA DOCUMENTACIÓN Y LA AGILIDAD? Charla sobre la documentación en la agilidad, con bases y recomendaciones para una buena documentación dentro de los entornos ágiles (y los no tan ágiles).

1. ¿PODRÍAN COEXISTIR LA
DOCUMENTACIÓN Y LA
AGILIDAD?
P o r D a n i e l R a m í r e z
@ n a s s a o
2 0 2 0 - 0 6 - 2 4

2. DANIEL RAMÍREZ
Desarrollador de corazón
Full Stack Developer / Scum Master en TCS
• Ingeniero de Sistemas y Máster en Business
Intelligence
• 23+ años desarrollando y 6+ años en la
agilidad y apenas me estoy enterando que
conozco sobre algunos temas…
@nassao
nassao@gmail.com
nassao.com
2

3. Sobre Daniel
Mi lugar en el mundo
• He desarrollado aplicaciones
en diferentes lenguajes,
usando diferentes
metodologías, para varios
segmentos dela industria.
• He generado documentación
en código y en físico,
utilizando diversas
herramientas y metodologías.
• Actualmente trabajo como
Líder Técnico para un
proyecto de DevOps en un
Banco.
• Una de mis funciones es
mantener la calidad del
código y garantizar la
existencia y actualidad de la
documentación.
3

4. Documentación
Extensa
E l l e g a d o d e l d e s a r r o l l o e n c a s c a d a

5. Elicitación de Requisitos
Requerimientos funcionales y no
funcionales, diagramas UML…
En cascada, necesitas construir un gran
número de documentos para tener un
soporte legal para el contrato:
• Diseño de pantallas
• Diseño de informes
• Diseño de archivos
Cualquier cambio que hagas en los diseños
deberá estar contemplado en un Otrosí que,
a su vez, deberás soportar con una gran
cantidad de nuevos documentos.

6. Maximizando El
Trabajo No
Realizado
P r i n c i p i o s d e L e a n y M a n i f i e s t o Á g i l

7. “ Elimina los desperdicios. Decide lo más tarde posible.”
- Principios de Lean.
7

8. LEAN
El arte de maximizar el trabajo no realizado
• Si no se necesita, no lo
documentes.
• Algunos documentos no son
necesarios en etapas
tempranas del desarrollo, pero
otros documentos si lo son.
• Documenta Just in Time.
Evita reprocesos.
• Documenta todo lo que
genere valor, todo lo que sea
requerido, todo lo que puedas
necesitar.
• Hay información útil o
bastante necesaria durante el
desarrollo. Esta
documentación te hará la vida
más fácil.
8

9. “Hemos aprendido a valorar…
Software funcionando sobre
documentación extensiva.
…Esto es, aunque valoramos los
elementos de la derecha, valoramos
más los de la izquierda.”
- Manifiesto por el desarrollo ágil de software
9
agilemanifesto.org

10. Manifiesto
Por el Desarrollo de Software
• Documentación no
extensiva no quiere decir
nula!
• Software funcionando genera
valor. Pero si hay que hacer
correcciones, ¿hay
documentación? o ¿vas a
trabajar a ciegas?
• La definición de Terminado
debe incluir la documentación
necesaria para cada Historia
de Usuario que haya sido
desarrollada.
• Toda documentación debería
estar disponible para todos los
miembros del equipo,
interesados y usuarios,
actuales y futuros.
10

11. “¡Es tan fácil de usar que no
necesita documentación!”
Mientras tanto, el usuario…
12

12. El Gusto Del
Desarrollador
L a p e r s o n a d i r e c t a m e n t e r e s p o n s a b l e p o r
g e n e r a r l a d o c u m e n t a c i ó n

13. El Desarrollador
Esa particular persona que transforma Post-it® en
Software
• Somos perezosos.
• Nuestra comunicación fluye si se
trata de hablar de juegos,
películas, series, tecnología,
lenguajes de programación.
• Nos asustamos fácilmente en
sociedad y somos incapaces de
decir no.
• Se nos dificulta escribir al nivel de
comprensión del usuario final.
• No nos gusta documentar.
• Dejar que se acumule la
documentación para el final del
ciclo de desarrollo significa que
debemos pasar días o semanas
enteras documentando.
14

14. Lo Que Se Usa Va
Primero
G e n e r a n d o d o c u m e n t a c i ó n q u e s e r v i r á
c o m o s o p o r t e e n e l d e s a r r o l l o y
m a n t e n i m i e n t o d e l p r o d u c t o

15. Cuando una aplicación
se vuelve en insoportable…
Al ingresar a un nuevo equipo, ¿cómo se
transmitirá el conocimiento?
Cuando se recibe una aplicación para su
soporte, ¿cómo permanecerá el
conocimiento en el tiempo?
Cuando se retoma una funcionalidad,
¿cómo se recordará fácilmente lo que se
conocía y se dominaba?

16. No Olvidemos Lo
Requerido
D o c u m e n t a c i ó n l e g a l y d e n e g o c i o

17. “Cualquier desarrollador
entiende a primera vista lo que se hizo
en el código.
¿Para qué repetir lo ya que se hizo en
los comentarios del commit?”
¿Qué tal si pensamos en el auditor?
18

18. Auditorías, leyes, lineamientos…
Cuando la obligación llama a la puerta
• La ley Sarbanes Oxley (SOX)
reglamenta estándares con
controles estrictos para evitar
fraude en la presentación de
la información financiera.
• Algunas aseguradoras exigen
que quede documentado el
proceso de aseguramiento de
la calidad.
• Todo aquello que se nos sale
de las manos, pero que es
requerido por algún proceso
interno o externo, debe
documentarse: así nosotros
no le veamos el valor,
alguien allí afuera lo valora.
19

19. Controles SOX
Cotizando en la bolsa de New York
• Después de los desfalcos de
Enron en el año 2001, todas
las empresas que cotizan en
la bolsa de Nueva York están
cubiertas por al Ley SOX de
protección al inversionista.
• Enron, con 21k empleados,
ingresos de 111k millones de
USD en el año 2000, se
declaró en bancarrota.
• Los accionistas perdieron 11
millardos de dólares (109)
• Se tribuyó la perdida a fallas
en la auditoría, escondiendo
deudas y pérdidas en
ejecución de proyectos.
• El sector banca tiene 4
controles SOX*.
• El sector Telecomunicaciones
tiene 10 controles SOX**.
• Estos controles aseguran
transparencia en los procesos
financieros, aumentan la
seguridad, facilitan las
auditorías.
• ¡Trazabilidad es
documentación!
20
* Bancolombia, mayo de 2019.
** Tigo Colombia, enero de 2020

20. Recomendaciones
D e s d e l a e x p e r i e n c i a , l o q u e h a f u n c i o n a d o

21. “Cualquier tonto puede escribir
código que un ordenador
entiende.
Los buenos programadores escriben
código que los humanos pueden
entender.”
- Martin Fowler
22

22. Documentación del Código
Lectura para humanos
• Utilizar nombres de variables,
funciones, etc., que sean fáciles de
relacionar con su significado y uso.
• Utilizar siempre las mejores
prácticas para generar código
limpio [Clean Code].
• Las pruebas en el desarrollo
basado en comportamiento BDD
en lenguaje natural, como las de
Cucumber, son en sí
documentación
• Los excelentes desarrolladores
logran que su código pueda ser
leído como una historia que se
cuenta sola.
23
Clean Code, por Robert C. Martin.

23. Documentación Útil
Centralizada y disponible
• Utiliza herramientas que te
permitan centralizar la
documentación, como wikis o
nubes.
• Utiliza herramientas colaborativas,
pero que permitan el
versionamiento y la trazabilidad.
• Las fotos de tableros y las notas
tomadas en un cuaderno
también son documentación.
• Trata de escribir en términos que
sean fáciles de entender para
quienes apenas llegan.
• No construyas documentos que
solo servirán para ocupar
almacenamiento o acumular polvo.
• No olvides generar la
documentación obligatoria (así no
le encuentres sentido).
• ¡Un buen código es
documentación!
24

24. “No terminas hasta no terminar”
Una excelente práctica es adicionar la
documentación a tu Definición de
Terminado (Definition of Done)
25

25. Documentación
y agilidad:
¡sí pueden
coexistir!
Daniel Ramírez
@nassao
nassao@gmail.com
nassao.com