Eu escribo unha morea de documentación no traballo. Propostas, deseños, análises, informes, manuais de usuario, manuais para enxeñeiros, … a escritura de documentación non ten fin. E sabedes o máis curioso? Que gosto de escribir toda esa documentación. No principio, igual que moitísima xente, pensaba que era un labor moi pesado e ingrato, pero despois decateime de dúas cousas.
A primeira cousa da que me decatei foi o tempo e esforzo que aforraba escribindo documentación. Tiven a fortuna de facer proxectos que a xente quería usar, así que sempre recibía consultas sobre as súas capacidades, a maneira de usalos, etc., e moi pronto quedou claro que era moito mellor escribir un manual de 15 páxinas que calquera podía descargar e ler, que escribir emails e ter reunións individuais con cada persoa que me quería facer unha consulta.
A documentación tamén me axudou no traballo remoto. Hai uns anos mudeime a Nova York, pero o meu equipo ficou en California. Cada vez que un novo compañeiro se incorporaba ao equipo, non podía sentar con el para lle aprender como funcionaba todo e responderlle todas as súas dúbidas no momento, así que escribín manuais que podía ler e consultar pola súa conta, e que resultaron ser moi apreciados.
A segunda cousa da que me decatei é de que a escritura de documentación non é tan diferente do resto do oficio. Cando programo escribo un texto que instrúe ao ordenador na maneira en que ten que facer o que eu lle pido. Cando escribo documentación fago exactamente o mesmo, pero con persoas. Escribir documentación é programar xente. Tantos millóns investidos na intelixencia artificial, cando xa levabamos séculos programando intelixencias naturais.
Ás veces é difícil escribir documentación, especialmente cando abrimos o editor e temos unha páxina baleira e non sabemos como comezar. A maioría dos documentos que escribimos no noso oficio teñen como obxectivo describir algo: un deseño, un manual de usuario, un informe “post-mortem”, etc. Para escribir eses documentos, o mellor é facer como se forades xornalistas e responder unha serie de preguntas: “que”, “quen”, “para que”, “por que” e “como”.
“Que” é o punto máis importante, sen o que o documento non ten sentido. É tan obvio que, moitas veces, os autores dos documentos esquéceno por completo.
Hai pouco recibín un email avisando da extrema importancia dun proxecto que vou chamar “Peliqueiro” para preservar o seu anonimato. Co importante que era, ese email non explicaba que era o Peliqueiro, así que alá fun á súa páxina web. O primeiro 25% da páxina reiteraba a importancia do Peliqueiro, o seguinte 25% anunciaba as consecuencias de non usar o Peliqueiro, o seguinte 25% explicaba como usar o Peliqueiro e, xusto no final, un parágrafo mencionaba Laza e o Entroido, pero sen chegar a explicar que é un Peliqueiro.
Pois iso: non esquezades nunca o “que”.
“Quen” tamén é moi importante: quen escribiu o documento, quen traballa no proxecto, para quen é o documento, onde escribir se hai preguntas.
“Para que” e “por que” son preguntas moi semellantes, pero eu coido que é importante separalas. “Para que” pídenos que expliquemos a finalidade. Para que é o proxecto descrito no documento? Que problemas soluciona? Que pretendemos conseguir co documento? “Por que” pídenos que expliquemos a motivación. Por que precisamos dun proxecto? Por que o deseñamos así? Por que decidimos escribir este documento?
Por exemplo, imaxinade que sodes os inventores do automóbil. “Para que?” Para trasladar pasaxeiros e mercadorías. “Por que?” Os cabalos son lentos e caros de manter, os trens precisan de moita infraestrutura, as bicicletas precisan de moito esforzo físico, etc.
Finalmente, “como” debería ser obvio: detalles de implementación do proxecto, como usalo, como solucionar os problemas, etc.
Espero que, a próxima vez que vos enfrontedes ao terror da páxina en branco, este pequeno esquema vos axude.
A ilustración desta Folla procede dun gravado de Jean Jacques de Boissieu.
1 comentario