Cuando creas una extensión para Joomla, o para cualquier otro tipo de software, la documentación siempre será una parte importante del éxito de la extensión.

Hacer una buena documentación te permitirá ahorrar tiempo y dinero. Además, incrementará el nivel de satisfacción de tus clientes. Te presentamos una explicación detallada y algunos consejos sobre los 5 principales tipos de documentación que deben acompañar a una extensión.

Una buena documentación produce:

• Mayor satisfacción en los usuarios – Nadie quiere enviar un mensaje al Soporte Técnico o postear una cuestión en un foro y esperar una respuesta que puede no llegar nunca. Cuando tus clientes pueden encontrar toda la información que necesitan leyendo el manual o viendo video tutoriales, van a estar mucho más satisfechos.

• Menos consultas al Soporte Técnico – Con menos preguntas, perderás menos tiempo y dinero en soporte. Por lo tanto, podrás usar ese tiempo y dinero en añadir nuevas caracterísitcas o en crear  una nueva extensión.

5 Tipos de Documentación

Durante más de cinco años de trabajo en el desarrollo de extensiones Joomla, hemos aprendido que en lo referente a la documentación de la extensión, los diferentes clientes tienen necesidades diferentes. A algunas personas les encanta sentarse y leer el manual de cabo a rabo. Otros prefieren ver video tutoriales. Un manual no les es bastante.

Hemos identificado 5 tipos de documentación que necesita una extensión. Debes incluir tantas como puedas.

Si no tienes tiempo para crearlas todas tú mismo, contrata a alguien para ayudarte o pregúntales a tus clientes habituales si lo quieren hacer a cambio de actualizaciones gratis o cualquier otra compensación.

1. Manual

La documentación más básica es el manual. Algunas personas lo leerán de cabo a rabo; otras lo cogerán como referencia donde consultar dudas. Independientemente del uso que le vayan a dar, tu manual deberá estar siempre bien organizado, con contenidos fácilmente encontrables.

Un manual debe incluir siempre:

• Portada con el nombre de tu compañía y el logo, URL, el nombre de la extensión  y enlaces a Soporte Técnico, FAQ, Foro y Actualizar extensión.
• Índice.
• Una pequeña descripción.
• Requisitos mínimos (si existiesen).
• Instrucciones para instalar, desinstalar y actualizar.
• Características y trucos.

Asegúrate de incluir un pantallazo para cada característica; es más fácil explicar algo si puedes mostrar lo que quieres explicar. Asegúrate también de que el texto es suficientemente grade y  evita emplear texto claro sobre fondo oscuro. Crea tu manual con un procesador de textos, -MS Word, OpenOffice,...-, y cuando lo hayas terminado, pásalo a pdf.

2. Video tutoriales

Los video tutoriales son una magnífica vía para explicar diferentes aspectos y características de tu extensión. Aunque no seas un hablante nativo de inglés, si dominas este idioma suficientemente, puedes hablar en tu vídeo tutorial. ¡Y no te preocupes de como suenas! Las voces siempre nos suenas un poco estrañas al principio, pero rápidamente te acostumbrarás. Usa una herramienta como Camtasia Studio para grabarte mientras explicas cómo funciona tu extensión.

Una vez que los hayas hecho, además de alojar los vídeos en tu web, considera la opción de crear un enlace a tu vídeo tutorial en la zona de back-end de la extensión en que sea más útil. Tus clientes no tendrán deste modo que volver a tu web para ver los vídeo tutoriales y esto les será más cómodo. En iJoomla.com, empezamos a añadir enlaces a nuestros vídeo tutoriales en la mayoría de las extensiones hace un par de años y a nuestros clientes les ha gustado la idea.

OS training recientemente lanzó OSToolBar, una extensión que muestra un botón de vídeo en el backend de tu sitio Joomla. Es el mismo concepto de los enlaces a vídeos de los productos iJoomla pero se usa para but características generales de Joomla. Creo que este es el comienzo de una tendencia que continuará desarrollándose y espero que se convierta en un estándar de la comunidad Joomla.

3. Tooltips/Descripciones emergentes

Una tooltip es la pequeña caja con información que aparece sobre un elemento cuando un usuario coloca el cursor sobre él. Es una manera sencilla para enseñarles a los usuarios cosas acerca de las funciones de una página.

En general, hay 2 maneras de añadir una descripción emergente en una extensión Joomla:

• Añadiendo un icono de información que muestra la tooltip cuando pasamos por encima de él con el cursor;
• Añadiendo la tooltip en la etiqueta del campo (Lo que hace Joomla por defecto).

Prefiero la primera opción. Algunos usuarios saben que pueden pasar el cursor sobre la etiqueta pero no saben que la descripción emergente está presente hasta que pasan. Un icono es mucho más claro.

Una estrategia interesante es copiar la descripción de cada campo del propio manual. Todo será coherente y además no tendrás que escribir las cosas dos veces. Escribe primero tu manual, describe en él todos los campos y deja después que los clientes lo puedan consultar también mediante las descripciones emergentes.

Algunos desarrolladores de extensiones hacen un mal uso de estas tooltip. En vez de ofrecer la información necesaria para usar el elemento que la caja describe, únicamente repiten en élla la etiqueta del campo.

La manera correcta de escribir tus descripciones emergentes:

Describe qué hace ese campo y explica cómo usarlo. Por ejemplo, si solicitas un API, dile al usuario dónde puede encontrarlo. Si el campo se usa para subir un archivo, informa de qué tipos de archivos son soportados y del tamaño máximo de carga.

La manera incorrecta de escribir tus descripciones emergentes:

Repitiendo el nombre del campo.

4. Tutoriales escritos

Si sabes que tus clientes están preguntando cosas muy parecidas, dirígelos a un tutorial con distintos pasos e imágenes siempre que accedan a tu foro o sistema de soporte técnico. Esto te ahorrará muchísimo tiempo. Aquí hay un ejemplo de  un tutorial escrito que hemos creado para iJoomla Ad agency, hemos incluído un vídeo para las personas que prefieren los vídeo tutoriales.

5. Wiki

Un wiki es un sitio o un software que permite a los usuarios de manera conjunta crear y editar páginas web. Puedes añadir el contenido tú mismo o dejar que los usuarios de tus extensiones contribuyan.

No hemos tenido oportunidad de crear un wiki en iJoomla.com de momento, pero los wikis que he visto usar a otros desarrolladores son muy buenos. Un buen ejemplo es la página wiki de hwdmediashare: http://documentation.hwdmediashare.co.uk/wiki/Main_Page

Hay varias extensiones wiki para Joomla que puedes usar. No las he probado personalmente pero hwdmediashar emplea una llamada media wiki: http://www.mediawiki.org/wiki/MediaWiki.

Consejos:

Mantén tu documentación actualizada.

Si haces cambios en tu extensión, asegúrate de actualizar también la documentación, especialmente si los cambios son significativos.

Déjala para el final.

Es posible que hagas cambios en la extensión durante su desarrollo — hasta el último minuto— así que deja el trabajo de documentación para el final de todo, como el último paso antes de acabar.

Escribir una buena documentación te ahorrará tiempo y dinero, y hará más felices a tus clientes. ¿Qué otros métodos de documentación estás usando?

Fuente: magazine.joomla.org