Número 64
2 de agosto de 2023

A documentación

Unha vez, un amigo dun amigo chamoume para que lle fora botar unha man, xa que tivera un desastre e non lle andaban as copias de seguridade. Alá fun no meu coche e, logo de chegar, cando lle preguntei onde as tiña, apuntou co dedo á caixa de discos externa.
—Aí están, que teño os discos replicados por RAID.
Non foi moi agradable ter que lle explicar ao pobre home que o RAID non é unha copia de seguridade.

Unha señorita descende dunha carruaxe, axudada por un soldado.“Por fin chegamos! Moito andei!”

A ben seguro, nun sistema RAID os datos están duplicados e replicados igual que as copias de seguridade, pero non son copias de seguridade. O RAID non garda copias antigas dos ficheiros, senón que replica o estado actual en todos os discos o máis rápido posible. Se alguén borra un ficheiro, ese ficheiro fica borrado en todas as réplicas case instantaneamente: non é posible ir ao RAID e restaurar a versión de onte.

Venme á memoria o que sentín naquel día cada vez que alguén me di que a documentación do seu proxecto está no Slack ou no Discord ou nun foro.

Moita xente pensa que, como pasou moito tempo escribindo, o resultado é documentación, pero iso non é certo. A documentación ten que estar ben organizada e ben redactada, ten que estar actualizada, ser completa e ser accesible.

Os sistemas de chat e os foros non se prestan a iso: están deseñados para mensaxes curtas e comunicacións efémeras. En moitos destes sistemas, a busca non funciona moi ben, é difícil acceder a información antiga e tamén é difícil actualizala.

Polo tanto, escribide a vosa documentación nun sistema que se preste para iso, non no chat, ou heime ver obrigado, dentro duns anos, a contar a anécdota de como pensabades que tiñades documentación pero non podiades atopar nada nela.

A ilustración desta Folla é un gravado de Thomas Rowlandson.