Escribir documentación es una de las habilidades más importantes de un desarrollador.
Si alguien ha llegado a buscar algo que has escrito en Google, significa que está atascado. Estar atascado puede ser frustrante y molesto. Así que trata de no hacer que se sienta peor diciéndole lo fácil que debería ser encontrar lo que busca. Esto puede obstaculizar su capacidad para aprender lo que quieres que aprenda.
Es probable que tengas la tentación de que al escribir documentación sobre tus proyectos, quieras usar palabras como “sencillo”, “fácil”, “simplemente”, “nada más”.
Se entiende. Lo que quieres es contarle a tu usuario lo mucho que estás haciendo por él o ella, resaltando lo poco que tienen que hacer para resolver su problema ahora que va a utilizar tu solución.
Desafortunadamente, con lo que tu lector se va a quedar es con un sentimiento de frustración e insuficiencia, pues en lo que ha estado atorado todo este tiempo, resulta ser “fácil” de resolver.
Tenemos que ser más cuidadosos y compasivos al momento de escribir documentación. Si alguien la está consultando, es porque quiere aprender algo más. Lo menos que podemos hacer es procurar que las personas que nos leen no se queden con la idea de que, dhu, lo que estás buscando es OBVIO.