Como tecnólogo, pensé que necesitaría escribir cosas dos veces pero en realidad son tres
Read this article in:
tl;dr: código de producción, código de prueba y documentación.
Los contadores públicos certificados se utilizan para escribir las cosas dos veces, en el sistema de contabilidad de doble entrada. Esto ayuda a evitar algunos errores. Los programadores en idiomas interpretados, como yo, se utilizan para probar el desarrollo (TDD), donde cada pieza de funcionalidad está razonablemente cubierta por una prueba. De una manera que es un sistema de doble entrada. Sin embargo, al menos falta una pieza.
He encontrado que si no documento la funcionalidad, es como si desapareciera o nunca estuviera allí. Así que hice una regla para escribir alguna documentación para cada bit expuesto - ya sea una pieza de funcionalidad, o un elemento de una interfaz de usuario. Al menos, estoy haciendo una nota del trabajo realizado en el cambio/trabajo. Y lo hago público. Publique o perezca, bien, y si una funcionalidad es implementada por nunca utilizada, nadie es mejor para ella.
Describir la interfaz de usuario en un archivo README.txt es lo suficientemente bueno. Lo sé porque vuelvo a leerlos todo el tiempo. Llenar la carpeta doc/ en el repo también ha resultado útil. Si no recuerdo cómo se hizo algo, tal vez pueda leerlo allí. Y si escribo documentación que nunca será leída - hey, eso también está bien.
Muy a menudo la documentación falta o es sub-par. Al mismo tiempo, demasiados recursos en línea describen cosas que no existen, o son basura. ¿Por qué no reconciliamos a los dos? Programa herramientas útiles, *y* escribe la documentación sobre cómo utilizarlas.
Buen software merece buena documentación. La gran ingeniería no se trata sólo de escribir código. También se trata de compartir sus conocimientos y hacer que su experiencia sea útil.
