Si O’Reilly se animara alguna vez a publicar los títulos de Los 10 mejores libros de programación que NUNCA verás en las estanterías, probablemente “Copiando y pegando de Stack Overflow” se convertiría en un súper ventas.

[Pulsa para continuar]

Aunque el inglés es un idioma que yo considero que hablo bastante bien (academia, escuela oficial de idiomas, parte de la carrera en inglés…) siempre es agradable poder leer un texto en tu lengua materna. Esto es un problema cuando se trata de documentación técnica, porque las obras de referencia a menudo no se traducen al castellano o tardan mucho en publicarse, y en ocasiones los textos que podemos encontrar en nuestras tiendas cuentan con muy poca calidad.

En su día ya intenté aportar mi granito de arena publicando el libro “Python para todos” como Creative Commons, una iniciativa que no salió demasiado mal. Desde hace ya bastante tiempo tengo un especial interés por Android, y cuando empecé a dar mis primeros pasos comprobé que la situación no era mucho mejor.

Desde que Google creara el sitio de Android Training este ha sido un recurso que siempre ha estado muy bien considerado por los desarrolladores, hasta el punto de que muchos lo recomiendan como la mejor forma de comenzar con Android. Por eso, y porque una empresa que gana más de 10 000 millones de dólares al año todavía no se ha molestado, me he propuesto traducir estas clases al español, aprovechando su licencia Creative Commons.

Ya podéis encontrar las 3 primeras clases en Formación Android. No os deberían llevar más de 2 horas.

Si tenéis cualquier duda, fallo o sugerencia que comentarme, podéis utilizar, como siempre, el formulario de contacto o los propios comentarios de esta entrada. Y si os gusta la iniciativa y queréis darle un poco de publicidad en las redes sociales, mejor que mejor 😉

A menudo, la documentación del software consiste en grandes, pesados y amenazadores manuales que nadie nunca lee. De hecho, durante los últimos cinco años, la mayoría de los manuales que venían con productos software han sido en realidad copias de “La danza de la muerte” de Stephen King, con nuevas tapas pegadas.

— Dave Barry

Docstrings

En artículos anteriores del tutorial de Python ya comentamos en varias ocasiones que todos los objetos cuentan con una variable especial __doc__ mediante la que indicar el propósito y uso del objeto. Estos son los llamados docstrings o cadenas de documentación.

A estos atributos se les puede asociar el texto correspondiente explícitamente, asignándolo al literal cadena correspondiente, como con cualquier otra variable. Sin embargo, por conveniencia, Python ofrece un mecanismo mucho más sencillo y es que si el primer estamento de la definición del objeto es una cadena, esta se asocia a la variable __doc__ automáticamente.

[Pulsa para continuar]

La mayor parte de la documentación comienza consistiendo en pequeñas notas rápidas ilegibles escritas por desarrolladores privados de sueño y a los que no se les contrató necesariamente por su habilidad para la comunicación.

Estas notas las reescriben graduados en Filología que acaban de salir de la universidad y que pasaron sus últimos 4 años inmersos en obras de ficción.

El resultado se manda al departamento de marketing, cuyo trabajo consiste en asegurarse de que ninguna palabra o frase produzca una mala impresión del producto (“No creo que la palabra ‘Basic’ comunique adecuadamente la excitante naturaleza del producto. ¿Por qué no lo llamamos ‘Visual Zesty‘?”).

Por último los abogados terminan el trabajo asegurándose de que realmente no se haya prometido explícitamente que el producto haga algo útil.

Para cuando la documentación llega a tus manos, ha sido modificada más allá de lo reconocible y normalmente tienes que comprar un manual del producto editado por otra compañía en un vano intento de saber cómo usar el programa.

— Grettir Asmundarson en Networking @ Novell

Para seguir con el tema de los comentarios en el código, os dejo este enlace a un pequeño plugin que integra el sistema de documentación que suelo utilizar últimamente (Doxygen) en Eclipse. Eclox permite crear archivos doxyfile con la configuración a utilizar a la hora de generar la documentación y crear la documentación con un par de clics desde Eclipse.