El arte, parte y cultura de la documentación

Diana Rodriguez

$whoami

Diana Rodríguez

Google Developer Expert

Auth0 Ambassador

Microsoft MVP

🐍 Developer Advocate @ Vonage

🎖 https://superdi.dev

🐦 @cotufa82

$whoami-NOT

Efectos De La Cultura DevOps

La adopción de la cultura DevOps, herramientas y practicas ágiles de ingeniería tienen, por sobre todas las cosas, el lindo efecto de incrementar la colaboración entre los roles de desarrollo y operaciones.

Uno de los principales problemas del pasado (pero también hoy en día en algunas realidades) es que el equipo de desarrollo no estaba interesado en la operación y el mantenimiento de un sistema una vez que se entregó al equipo de operaciones, mientras que este último no estaba realmente consciente de los objetivos de negocio, y por lo tanto, reacios a satisfacer las necesidades operativas del sistema (también denominados “caprichos de los desarrolladores”)

Vue.js Docs

📜

El Arte

Escribir documentación es un ejercicio de empatía. No estamos describiendo una realidad objetiva, el código fuente ya lo hace. Nuestro trabajo es ayudar a dar forma a la relación entre quien usa ese código y el propio ecosistema que se está creando al rededor de ese código.

Recordando lo esencial

Usar voz activa
Evitar el uso de terminología complicada
Buena ortografía
Usar contexto visual para aclarar conceptos

☝🏼

✨ https://v3.vuejs.org/guide/contributing/writing-guide.html

Principios

Un feature no existe hasta que esté bien documentado
Respetar la capacidad cognitiva de lxs usuarixs
Escribir desde la perspectiva de lxs usuarixs
Describir el problema -primero- y luego la solución
La peor pregunta es la que no se hace
"Documentation-Driven-Development": Hacer features que sean sencillas de explicar, o poder explicarlas incluso antes de su desarrollo y no solo desarrollar y luego preocuparse de explicarlo después.