¿Ya es hora? El tiempo vuela cuando estás escribiendo artículos, y de golpe te das cuenta que ya está aquí el día que tienes que entregar el artículo. Supongo que es lo mismo para las personas que escriben documentación sobre su extensión. La mayoría de nosotros, como usuarios, basta con ver la demo, la descripción breve, y luego descargar e instalar ... Pero te voy a dar algunas razones por las que tenemos que añadir el paso de leer la documentación …

La última vez que instalamos una extensión, necesitamos acudir al soporte, esta vez, para asegurarnos, estamos leyendo la documentación, que es muy posible que sea una parte del soporte propuesto por el desarrollador. Si utiliza una extensión de un desarrollador competente, ¡seguro que estará disponible la documentación! Esto no quiere decir que otras extensiones que no tienen documentación disponible sean malas, pero el que la tenga, da más garantías de que recibirás ayuda si la necesitas.

¿Qué tipo de ayuda? Instalación, configuración, solución de problemas, los campos adicionales, comportamientos, etc .. están todos descritos en una buena documentación.

RTFM*...

A veces nos olvidamos o pensamos...''para qué leer estas 100 páginas, o más, que alguien escribió como si fuera un diccionario…” Tal vez no desee leerlo, pero debería…

Los desarrolladores que escribieron la documentación hacen todo esto para mostrarle realmente cómo utilizar la extensión, las posibilidades que tiene y cómo configurarla. Sin embargo a veces la documentación no sigue el control de versiones de las extensiones con precisión ... por ejemplo: la extensión está en la versión 3, mientras que la documentación se encuentra todavía en la versión 2. Lo cual es comprensible, desde mi punto de vista, a veces un desarrollador necesita actualizar la nueva extensión, debido a un error o característica nueva y no tiene tiempo para volver a escribir la documentación. Sobre todo si las versiones son muy similares … pero es importante que lo realice, por bien del usuario.

Una buena documentación debe tener al menos cuatro partes. Instalación, configuración, personalización y solución de problemas.

Instalación

Está bastante claro lo que se debe de describir en este apartado. Y las personas que están seguras de que sólo instalar el paquete es suficiente ¡lo plantean mal! A veces es necesario añadir, activar o desactivar algunos plugins, cambiar una pequeña configuración en el servidor o la configuración php ... Para las extensiones básicas, no es problema, pero cuando se está añadiendo una extensión importante del JUG a su sitio, esta información podría ser necesaria. Cuando me paso  un problema como este la primera vez, me di cuenta de la importancia de esta documentación, y desde entonces no uso una extensión sinno tiene una buena documentación.

Configuración

¿Qué pasa con la configuración? Esto depende de qué características tenga la extensión. Una extensión de noticias sencilla, tendrá mucha menos documentación sobre la configuración que una suscripción de extensiones con gran cantidad de funciones adicionales como boletín, pagos, renovaciones automáticas, grupos de usuarios, etc .. Un buen manual describe cada paso de la configuración, en realidad cada paso. Tal vez tenga más de 20 páginas, si se hace de esa manera, pero mejor leer un poco más, que tirarse de los pelos después... Incluso si no está usando todas las características, si las lee, es posible que descubra una característica que le va bien utilizar en un futuro cercano o que ni siquiera sabía que existía…

Personalización

La personalización depende realmente de qué extensión se trate. Algunas extensiones no pueden ser modificadas para añadir requisitos particulares (excepto si sobrescribe). Pero si ha elegido una, donde es posible la personalización, esta parte le debería de ser de gran ayuda. Cuando estaba desarrollando un sitio web con un modelo de suscripción, el manual me dio todo lo que necesitaba saber sobre la personalización de la aplicación y así no tenía que "molestar" al desarrollador.

Resolución de problemas

Y por último, pero no menos importante, la resolución de problemas. Una buena documentación cubre gran parte de la solución de problemas. ¡Imposible de abarcar todo!, porque entonces no se necesitaría ningún tipo de soporte, ¿no ...? Los problemas que se producen frecuentemente, y siempre tienen la misma solución, son cuestiones que deben estar en la guía de solución de problemas (FAQ). Si, como usuarios hacemos algo mal, la solución es enviar un tiquet al desarrollador, puesto que no es un problema documentado ni común…

Así que una buena documentación nos puede ayudar mucho, si el desarrollador no la ofrece... es su decisión. Pero como usuario, cuando existe, deberíamos leerla, ciertamente, aunque solo sea por agradecimiento a los desarrolladores, que se han pasado mucho tiempo escribiéndola para ayudarnos...

Ahora ya sabe lo que significa la abreviatura RTFM* ;-)

* Para los que no sepan el significado de esta abreviatura RTFM, véanlo en la Wikipedia :-)

Título original: How to Choose an Extension? Part 3: Documentation
Autor: Mike Veeckmans