¿Deberían los programadores prestar atención a la redacción de documentación? Esta es una pregunta aparentemente menor pero bastante importante. Además de los programas y los datos, el software también incluye la documentación. Además, si un programador solo sabe escribir programas y no puede describir sus ideas de manera adecuada y elegante en la documentación, entonces es realmente un "code farmer".

La importancia de escribir documentación

Para las industrias relacionadas con el software, tanto en la escuela como en el trabajo, quizás todos ya han notado que, además de los programas que hay que escribir y los diagramas de diseño que hay que dibujar,hay otro trabajo importante que es escribir documentación.¿Por qué escribir documentación? Porque tenemos que mostrar lo que hacemos, no solo a los colegas, sino también posiblemente al personal de otros puestos, e incluso a los usuarios. Si solo sabemos escribir programas y no podemos describir nuestras ideas de manera adecuada y elegante en la documentación, entonces realmente nos convertimos en "code farmers".

He notado que, de hecho, son muy pocos los colegas a mi alrededor que saben escribir documentación de alta calidad. El profesor Kai-Fu Lee, en elprólogo de 'La cima de las olas',dice: "Conozco a muchos ingenieros de primer nivel, pero los excelentes ingenieros con una gran capacidad narrativa que conozco se pueden contar con los dedos de una mano." Ciertamente, entre los colegas que conozco, también son muy pocos los que pueden expresar claramente sus ideas en la documentación.

En cuanto a la escritura de documentación, los problemas que me han dejado una profunda impresión son los siguientes:

1. Todos los días enviamos y recibimos muchos correos electrónicos. Los he examinado detenidamente y he visto que muchos de ellos contienen frases poco fluidas, muchos errores tipográficos, o uso incorrecto o ausencia de signos de puntuación. Muchas veces, al interpretar un correo desde diferentes perspectivas, este puede tener muchos significados distintos, lo que hace que uno no sepa qué es exactamente lo que quiere expresar, reduciendo enormemente la eficiencia del trabajo.
2. Además del código, los proyectos también incluyen una gran cantidad de documentación. Al abrir la mayoría de los documentos, lo primero que percibo son estas sensaciones:Maquetación descuidada, formato incorrecto, frases poco fluidas y errores tipográficos por todas partes.Se nota a simple vista que el autor no escribió el documento con seriedad, y que además sus habilidades de expresión y organización de frases no son sólidas.
3. Cuando los miembros del equipo del proyecto discuten, casi todos hablan de cómo escribir bien los programas, pero no mencionan cómo esforzarse por mejorar en la redacción de documentos. Todos parecen coincidir en que la responsabilidad del desarrollador es escribir bien el programa, y todo lo demás es secundario.

La definición tradicional del software informático es: el software es la otra parte del sistema informático que depende del hardware; el software incluye el conjunto completo de programas, datos y su documentación relacionada.Nótese que aquí se menciona la "documentación relacionada". Si la documentación no está bien escrita, el software no puede considerarse un buen software. De hecho, es frecuente que el software tenga funciones completas, pero que se produzcan fallos debido a problemas de documentación.

En general, durante el proceso de desarrollo de software, los principales documentos involucrados en las diferentes etapas se muestran en la siguiente figura:

Se puede ver que en diferentes etapas del software se deben redactar diferentes documentos. En la etapa de planificación, es necesario redactar documentos de diseño detallado, documentos de plan de pruebas unitarias y documentos de plan de pruebas de integración, etc. En la etapa de desarrollo, también son estos mismos documentos, pero en versiones revisadas, porque durante el proceso de desarrollo real encontraremos lugares donde el diseño anterior es irrazonable o no se consideró adecuadamente, lo que requiere modificar los documentos anteriores. En la etapa de pruebas, se deben redactar informes de pruebas unitarias, informes de pruebas de integración e informes de pruebas de sistema, etc. En la etapa de publicación del software, se deben redactar manuales de instalación, manuales de usuario, guías de actualización, etc. Estos documentos están dirigidos principalmente al personal de soporte en campo y a los usuarios, por lo que deben escribirse de la manera más clara y comprensible posible, y nunca deben existir situaciones ambiguas; de lo contrario, solo habrá que esperar las quejas de los usuarios.

Para escribir buena documentación, primero debemos corregir una idea: la de que la documentación no es importante. Hay que situar la documentación al mismo nivel de importancia que el programa.

¿Cómo escribir documentación de alta calidad?

Entonces, ¿cómo podemos escribir documentación de alta calidad? Creo que podemos empezar por los siguientes aspectos:

1. Cambiar la idea de que la documentación es algo secundario y tratar con seriedad cada documento que escribimos en nuestro trabajo habitual.
2. En cuanto a la redacción de correos electrónicos, hay que expresar con precisión lo que se quiere decir. Antes de enviar el correo, vuelve a revisar si el contenido está completo, si hay errores tipográficos, si las frases son fluidas, etc.
3. Durante el proceso de redacción de documentos, hay que seguir estrictamente la plantilla especificada por el equipo del proyecto. Después de terminar el documento, realiza una revisión gramatical para corregir errores tipográficos y errores de gramática. En general, las frases con errores gramaticales aparecen subrayadas con una línea ondulada de color verde. Antes de enviar el documento, vuelve a leerlo por completo para ver si hay omisiones o deficiencias.
4. En el tiempo libre, se pueden leer libros o artículos que mejoren la capacidad de expresión lingüística y de escritura, y observar cómo otros exponen claramente sus ideas. Por ejemplo, leer con frecuencia las publicaciones de excelentes blogueros en CSDN es una buena manera de mejorar las habilidades de escritura.

En resumen, al igual que con otras cosas, escribir documentación también refleja la actitud de una persona. Escribir documentación de alta calidad no solo puede mejorar la imagen personal (si ves un buen documento, ¿no valoras también más a su autor?), sino que también puede mejorar la imagen del producto ante los clientes. Con este análisis, realmente es necesario dedicar más esfuerzo a escribir documentación.

Para hacer bien una cosa, debemos esforzarnos en todos los aspectos. En el proceso de desarrollo de software, escribir bien el código es importante, pero también lo es expresar claramente las ideas en la documentación. El "código" y la "documentación" son como los dos brazos de una persona; hay que hacer que ambos se desarrollen de manera equilibrada y no ocuparse solo de uno.

Fuente:CSDNAutor: Zhou Zhaoxiong