Cómo escribir documentación ÚTIL

English version

Hace no demasiado cambié de empresa. Llevaba más de dos años en dicha compañía, y en ese tiempo te da lugar a hacer muchas cosas. En mi caso, en gran parte del código existente en mi departamento y en las decisiones tomadas había tenido un papel importante. Por ello, era especialmente aconsejable que dejase una buena documentación en el departamento para las personas que me sustituyesen.

Sin embargo, ¿cómo se hace realmente una buena documentación? y, sobre todo, ¿cómo se escribe una que sea útil? A raíz de esa pregunta, leí muchos artículos y estuve preguntando a muchos compañeros en busca de un poco de iluminación. Este es el resultado de mis pesquisas.

¿Para quién es?
Antes de nada, es importante saber para quién estás escribiendo la documentación. No es lo mismo escribirla para un equipo que ya está trabajando en un proyecto, para un usuario final o para alguien nuevo que acaba de entrar entrar.

En este artículo me voy a centrar en escribir documentación para personas que eran previamente ajenas a la compañía, aunque muchos puntos se pueden utilizar para otro tipo de lectores.

Explicación inicial
Puede que la persona que recién entre en la empresa no sepa nada sobre el proyecto, así que está muy bien si hay una explicación inicial de qué hace el proyecto, cómo funciona y hasta dónde llega.

En esta primera descripción puedes explicar todo lo necesario para entender la plataforma: tipos de usuarios y qué puede hacer cada uno de ellos, todos los productos, las diferentes licencias y sus permisos… Todo lo necesario para alguien que esté completamente fuera de contexto. Como si le estuvieras contando a tu maravillosa abuela a lo que te dedicas.

Guía de instalación y arranque
Esa nueva persona que ha entrado no tiene ni idea de por dónde empezar, así que empecemos por lo más importante: cómo instalar tu proyecto. Describe paso a paso todo lo que necesitan realizar antes de poder instalarlo. Para mejorar esta explicación puedes adjuntar los comandos y las capturas de pantallas que veas necesarias.

Una vez que ya sepa cómo hacerlo, necesitará conocer cómo puede empezar a trabajar, así que el siguiente paso es añadir un tutorial para arrancarlo. En esta misma línea, dejar documentados cómo se realizan los despliegues a producción es primordial.

Tutoriales
Hemos hablado sobre escribir tutoriales para instalar y arrancar la aplicación, sin embargo, habrá otras circunstancias en las que estos sean útiles. Localiza esas situaciones o procesos que serían más sencillos con una guía paso a paso y escríbelas. No olvides las capturas de pantallas, los links que puedan ser necesarios y demás materiales útiles…

Estructura el contenido
Si tienes mucho que contar… mejor que esté ordenado. Es muy posible que las personas no tengan la necesidad de leer tu documentación entera siempre. Habrá circunstancias en las que solamente sea pertienente consultar una parte de ella. Por ello, organízalo correctamente para que se puedan encontrar los temas más importantes de forma sencilla. Del mismo modo, dale jerarquía a tu contenido. Eso también ayudará a la hora de localizar lo que se busca.

Librerías y metodologías
Es útil que dejes centralizado en algún sitio todas las librerías y las metodologías que se están usando. En el caso de las primeras, junto a ellas es conveniente que expliques qué versión estás utilizando y para qué específicamente se emplean.

Por el contrario, para las metodologías es valioso que introduzcas un link a ella. Puede que no todo el mundo la conozca. Por ejemplo, si se tomó la decisión de usar Diseño Atómico, indica dónde podrán leer más sobre este. Si no es una metodología que esté documentada de forma externa, deberás dejar constancia de ella también en este documento.

Arquitectura y decisiones
Los seres vivos de nuestro equipo no están dentro de nuestra cabeza, por ello, es necesario explicar la arquitectura que se está empleando. Asimismo, es muy importante que justifiquemos por qué ciertas cosas se hicieron de una forma u otra, ya que así evitaremos que se cometan ciertos errores en los que ya se cayó.

En esta misma línea, es conveniente que indiques decisiones como la nomenclatura que se utiliza para las variables, si se emplean espacios o tabulaciones, los breakpoints más usados…

Errores
Si hay errores o circunstancias que sucedieron o suceden con frecuencia, pon especial cuidado en documentarlos. También presta atención a partes del código que pueden desembocar en otros problemas si se modifican de cierta forma, o a fragmentos de la aplicación que puedan ser delicados. Cuanto menos tiempo se pierda en esta clase de incidencias mejor.

Usa todo lo necesario
Entender la cabeza de otra persona no es fácil, así que válete de todos los recursos que te ayuden a hacerlo más fácil: capturas de pantallas, links, comandos, diagramas, trozos de código (no olvides incluir en qué ficheros están),… Incluso puede ser útil que utilices como ejemplo un PR en el que modificaste cierta parte de una funcionalidad o en el que arreglaste cierto bug, para ilustrar por qué algo se hizo así.

Documenta tu propio código
Hay una frase que se usa mucho y es que el “código debe entenderse por sí solo” y es completamente cierto. No obstante, habrá situaciones en las que esto no sea tan sencillo. Para estas situaciones: documentar, documentar y documentar.