Oh, por dónde empezar …
Bueno, te lo diré – al principio. La documentación (y el software) que no apestan están diseñados para no chupar desde el principio. Cuanto más cerca del final de una fase de desarrollo considere la documentación (o, más precisamente, la historia que le contará a las personas sobre su software), más la documentación (y, a menudo, el software) apestará. ¿Por qué? No fue diseñado para no chupar. Sencillo.
Si no diseñas algo para no chupar, lo más probable es que te vaya a chupar.
Cuando el software está diseñado desde el principio con la documentación en mente, el software tiende a encajar de manera más limpia. Esto es, en parte, porque a lo largo del camino, las personas preguntan “¿cómo va todo esto cuando lo describimos? ¿Cómo va a funcionar esto cuando una parte se usa con otra? ¿Qué aspecto tendrá el código cuando las personas apliquen nuestras clases y métodos? “Esa perspectiva ayuda a eliminar mucha confusión en el código y reduce la necesidad de una explicación compleja. Esa perspectiva también casi hace que la documentación se escriba por sí misma.
- ¿Por qué la gente odia las películas de acción en vivo de Transformers?
- ¿El odio nazi a los judíos infectó la opinión pública en otros países?
- ¿Odias el ISIS?
- Cómo lidiar con ser odiado por mi familia tóxica
- ¿Por qué los autores dan muerte simple a los personajes más odiosos?
Un caso más común, o por lo que parece por la forma en que se formuló la pregunta, es el de “bueno, obtendremos el código resuelto, luego estará listo para los forjadores de palabras (para entrar y tratar de tener sentido de nuestro diseño y explicárselo a los demás … .oh, y se enviará la próxima semana … oh, y no hay documentos de proyecto, porque somos ágiles).
¿Cómo diablos podría alguien pensar que el enfoque entregaría documentación de calidad? Bueno, no lo hacen, y no lo hace. Y, eso parece estar bien con todos (porque, hey, enviamos, ¿no?).
Pero, así es como se obtiene la documentación que apesta.
Entonces, ¿cómo se obtiene una buena documentación?
- Considere la documentación desde el principio, al igual que considera cualquier otra característica o aspecto de la aplicación / producto.
- Tenga un producto sólido que sea utilizable (esto se aplica a las API, BTW).
- No invente más términos y conceptos nuevos de los que necesita (y retroceda y reemplace aquellos con algunos términos en lenguaje sencillo, también).
- Usa los términos y conceptos que tengas constantemente. Si te encuentras diciendo que “el usuario lo resolverá”, eso significa que no está terminado y tienes más trabajo por hacer.
- Involucre al (los) escritor (es) desde el principio y pregúnteles, “¿cómo se verá / suena esto en la documentación?” Si dicen algo extraño, pregunte cómo puede mejorarse.
Hay más, pero si solo sigue estos pasos, producirá un producto y documentación que son mejores que la mayoría.