Docs for Developers

2021, por Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, Heidi Waterhouse

Prefacio

Por Kelsey Hightower
La ausencia de documentación es como la kryptonita para un superhéroe programador, ya que la documentación desempeña un papel crucial en el ciclo de trabajo de un desarrollador.
De hecho, debería considerarse como la primera funcionalidad a implementar en cualquier proyecto.
La falta de documentación suele deberse a la falta de comprensión sobre cómo llevar a cabo el ciclo de documentación, el cual es tan vital como el ciclo de desarrollo y ambos deben ir de la mano para garantizar el éxito del proyecto.
A partir de mi experiencia personal en la creación de documentación, particularmente en proyectos como Kubernetes (Kubernetes the Hard Way), he aprendido la importancia y el impacto positivo que una buena documentación puede tener en la comunidad de desarrolladores.
El proceso presentado en este libro ha demostrado ser eficaz y funcional.

Hay situaciones donde vemos que tener documentación nos ahorraría tiempo y muchos sufrimientos.
- Como cuando tenemos que volver a ver nuestro propio código tiempo después y ya no está claro para nosotros.
- Como cuando los clientes tienen muchas preguntas que se repiten y repiten.
Tener documentación eficaz es necesaria, principalmente en proyectos que alcanzan cierta complejidad y extensión, que suelen ser la mayoría de los proyectos que valen la pena desarrollar.
Ayudando a desarrolladores con la documentación, vimos que no era la primera vez que lo habían intentado.
Este libro es una guía desde cero para crear documentación eficaz. Desde la planificación, la edición, la publicación, hasta el mantenimiento y la medición de la eficacia.
Usaremos como ejemplo un servicio ficticio, llamado Corg.ly, que traduce ladridos de perro en lenguaje humano.
En el equipo de Corg.ly participan
- Charlotte (líder)
- Karthik (ingeniero de software)
- Mei (cliente)
- Ein (mascota y beta tester)
El libro es agnóstico respecto a lenguajes y herramientas.