Manual de usuario y documentación JavaScript con JSDoc. Tutorial con ejemplos

En el mundo del desarrollo de software, la documentación adecuada y los manuales de usuario son la clave para desbloquear el potencial de nuestros proyectos. Desde la documentación del código JavaScript hasta la creación de un README.md informativo, aquí te revelo cómo proporcionar a tus colaboradores y usuarios una guía clara para comprender y utilizar tu trabajo.

Vamos a explorar en profundidad las mejores prácticas para documentar proyectos de manera efectiva. Descubre cómo dar formato a tus README, utilizar JSDoc para tu código JavaScript y mucho más.

Prepárate para llevar tus proyectos al siguiente nivel a través de la documentación bien elaborada. ¡No te lo pierdas!

¿Cómo se documenta una aplicación web?

La documentación de una aplicación web es un proceso importante que implica la creación de material informativo y de referencia que ayuda a los desarrolladores, usuarios y otros interesados a comprender y utilizar la aplicación. Veamos los pasos y elementos clave para documentar una aplicación web:

1. Documentación técnica:
   • Arquitectura: Describe la estructura general de la aplicación web, incluyendo componentes, capas y relaciones entre ellos.
   • Tecnologías utilizadas: Enumera las tecnologías, lenguajes de programación, bases de datos y otros recursos utilizados en la aplicación.
   • Requisitos del sistema: Especifica los requisitos mínimos del sistema para ejecutar la aplicación, como versiones de navegadores compatibles, sistemas operativos, etc.
2. Guía de instalación:
   • Proporciona instrucciones detalladas sobre cómo instalar y configurar la aplicación web en un entorno específico, incluyendo la configuración del servidor, bases de datos y otros componentes.
3. Guía de uso:
   • Introducción: Describe la funcionalidad general de la aplicación y su propósito.
   • Registro y autenticación: Explica cómo crear cuentas de usuario, iniciar sesión y gestionar contraseñas.
   • Flujo de trabajo principal: Detalla los pasos para realizar tareas comunes dentro de la aplicación.
   • Funcionalidades avanzadas: Explica características más avanzadas y opciones de configuración.
4. API (si corresponde):
   • Documenta cualquier API que la aplicación ofrezca para la interacción con otros sistemas o desarrolladores externos. Esto debe incluir una descripción de las rutas, parámetros, métodos HTTP admitidos y ejemplos de solicitud y respuesta.
5. Guía de administración:
   • Si la aplicación web tiene una interfaz de administración, proporciona instrucciones sobre cómo gestionar usuarios, configuraciones y otras tareas administrativas.
6. Ejemplos y tutoriales:
   • Proporciona ejemplos de código y tutoriales que ilustren cómo utilizar la aplicación web en casos de uso específicos.
7. FAQ (preguntas frecuentes):
   • Crea una sección de preguntas frecuentes que aborde las preguntas más comunes de los usuarios y proporciona respuestas claras y concisas.
8. Documentación de diseño (si corresponde):
   • Describe la interfaz de usuario, los flujos de usuario y los principios de diseño utilizados en la aplicación.
9. Actualizaciones y cambios:
   • Mantén un registro de cambios y actualizaciones en la aplicación, para que los usuarios y desarrolladores estén al tanto de las nuevas características, correcciones de errores y cambios importantes.
10. Soporte y contacto:
    • Proporciona información de contacto para obtener ayuda y soporte técnico.

La documentación puede presentarse en forma de documentos escritos, wikis, tutoriales en video, o como parte de la propia aplicación web (por ejemplo, a través de tooltips y ayudas contextuales). Es importante mantener la documentación actualizada a medida que se realizan cambios en la aplicación y estar atentos a los comentarios de los usuarios para mejorarla.

¿Son lo mismo la documentación de la aplicación y el manual de usuario?

La documentación de la aplicación web y el manual de usuario son dos tipos de documentación diferentes que sirven para propósitos distintos en el desarrollo y uso de una aplicación web.

La principal diferencia es que la documentación de la aplicación va dirigida a personas con perfil técnico y el manual de usuario no.

Documentación de la Aplicación Web:

1. Dirigida a Desarrolladores y Equipo Técnico: La documentación de la aplicación web está destinada principalmente a desarrolladores, ingenieros y otros miembros del equipo técnico que trabajan en el desarrollo, mantenimiento y mejora de la aplicación.
2. Detalles Técnicos: Contiene información técnica detallada sobre la arquitectura, la base de código, las API, las tecnologías utilizadas y otros aspectos relacionados con el desarrollo de la aplicación.
3. Ejemplos de Código: Puede incluir ejemplos de código, instrucciones de instalación y configuración del entorno de desarrollo, información sobre bases de datos y otros detalles técnicos.
4. Documentación de APIs: Si la aplicación ofrece una API, la documentación de la aplicación web puede incluir descripciones detalladas de las rutas de la API, los métodos HTTP admitidos, los parámetros y las respuestas.
5. No Necesariamente Orientada al Usuario Final: Por lo general, no se enfoca en proporcionar instrucciones detalladas sobre cómo utilizar la aplicación desde la perspectiva del usuario final.

Manual de Usuario:

1. Dirigido a Usuarios Finales: El manual de usuario está diseñado para los usuarios finales de la aplicación web, es decir, las personas que utilizarán la aplicación para llevar a cabo tareas específicas.
2. Instrucciones de Uso: Proporciona instrucciones detalladas sobre cómo utilizar la aplicación, desde cómo registrarse e iniciar sesión hasta cómo realizar tareas específicas dentro de la aplicación.
3. Capturas de Pantalla e Ilustraciones: Puede incluir capturas de pantalla, diagramas y otras ilustraciones que ayuden a los usuarios a comprender mejor cómo funciona la aplicación.
4. Solución de Problemas: A menudo, incluye secciones de solución de problemas y preguntas frecuentes para ayudar a los usuarios a abordar problemas comunes.
5. No se Enfoca en Aspectos Técnicos Internos: En general, no se adentra en los detalles técnicos internos de la aplicación, como la arquitectura de software o la implementación de funciones.

¿Cómo se hace un manual de usuario de una aplicación?

Paso 1: Identifica a tu audiencia

Antes de comenzar a redactar el manual de usuario, es importante comprender a quién va dirigido. Considera el nivel de experiencia de tus usuarios, su conocimiento del software y sus necesidades específicas.

Paso 2: Recopila información

Reúne toda la información relevante sobre la aplicación que planeas incluir en el manual. Esto puede incluir detalles técnicos, flujos de trabajo, instrucciones de instalación y configuración, y cualquier otra información importante.

Paso 3: Estructura el manual

Crea una estructura lógica para el manual que permita a los usuarios encontrar rápidamente la información que necesitan. Algunas secciones comunes incluyen:

• Introducción: Una descripción general de la aplicación y su propósito.
• Requisitos del sistema: Especificaciones técnicas mínimas para usar la aplicación.
• Instalación y configuración: Instrucciones detalladas para instalar y configurar la aplicación.
• Inicio rápido: Guía de inicio rápido para los usuarios.
• Funcionalidades principales: Describe las características y funciones clave de la aplicación.
• Solución de problemas: Incluye una sección de preguntas frecuentes (FAQ) y cómo solucionar problemas comunes.
• Referencias: Lista de recursos adicionales, enlaces a la documentación técnica, etc.

Paso 4: Escribe contenido claro y conciso

Cuando escribas el contenido del manual, asegúrate de que sea claro y fácil de entender. Utiliza un lenguaje sencillo y evita jerga técnica innecesaria. Proporciona ejemplos, capturas de pantalla y diagramas para ilustrar conceptos y pasos.

Paso 5: Da formato y diseño agradable al manual

Utiliza un formato limpio y organizado para que el manual sea fácil de leer. Considera el uso de encabezados, listas con viñetas, tablas y negritas para destacar información importante.

Paso 6: Revisa y edita

Revisa y edita el manual para corregir errores gramaticales y de ortografía. Asegúrate de que las instrucciones sean precisas y coherentes.

Paso 7: Obtén feedback

Haz que otros miembros del equipo o usuarios potenciales revisen el manual y proporcionen retroalimentación. Esto puede ayudar a identificar áreas que necesitan mejorar y garantizar que el manual sea útil y efectivo.

Paso 8: Formato de entrega

Decide cómo entregar el manual a los usuarios. Puede ser en formato impreso, un archivo PDF, una página web o incluso dentro de la propia aplicación como ayuda contextual.

Paso 9: Mantenimiento continuo

La documentación no es estática. A medida que la aplicación evoluciona, es importante mantener el manual actualizado para reflejar cambios en características y funcionalidades.

Crear un manual de usuario efectivo requiere tiempo y atención a los detalles, pero puede ser una herramienta valiosa para ayudar a los usuarios a aprovechar al máximo tu aplicación, fidelizar y reducir la carga de soporte al cliente.

Actividad propuesta de manual de usuario

Diseña un manual de usuario con un procesador de texto para la aplicación web o móvil que tú elijas. Además de lo que hemos visto ya, el documento deberá contener:

1. Una portada con el dato identificativo del documento (aplicación, versión, fecha).
2. Prólogo (información de uso de la documentación).
3. Tabla de contenidos.
4. Tabla de ilustraciones.
5. Páginas de contenidos (funcionamiento de la aplicación).
6. Sección de FAQ.
7. Fuentes de información relacionadas (si procede).
8. Glosario.
9. Índice.

Utiliza las capturas necesarias para ilustrar el documento.

Actividad vía http://www.laurafolgado.es/desarrollointerfaces/2017/01/ejercicio-ut3e1-documentacion-de-una-aplicacion-movil/

 

 

Laura Folgado

Vamos ahora con los detalles técnicos:

¿Cómo se documenta adecuadamente el código JavaScript?

La documentación adecuada del código JavaScript es esencial para que otros desarrolladores o incluso tú mismo en el futuro, si tienes tan mala memoria como yo, puedan entender y mantener el código de manera eficiente.

1. Comentarios descriptivos: Utiliza comentarios para explicar el propósito de las funciones, métodos y secciones de código. Debes incluir comentarios al comienzo de los archivos y funciones para proporcionar una visión general del contenido.

// Este es un comentario descriptivo para una función function 
miFuncion() { // Código de la función aquí }

2. Documentación de funciones: Para cada función o método, documenta sus parámetros, lo que devuelve y una breve descripción de lo que hace. Puedes utilizar la convención JSDoc para esto (más abajo hay más recursos de esto).

/** 
* Suma dos números. 
* @param {number} a - El primer número. 
* @param {number} b - El segundo número. 
* @returns {number} La suma de a y b. 
*/ 
function suma(a, b) { return a + b; }

3. Nombres descriptivos: Utiliza nombres de variables y funciones descriptivos para que sea evidente su propósito. Esto reduce la necesidad de comentarios innecesarios.

let totalVentasMensuales = 1000;

4. Evita comentarios obvios: No documentes lo obvio. Los comentarios deben proporcionar información que no se pueda inferir fácilmente del código. Por ejemplo, evita comentarios como i++ // Incrementa i en 1.
5. Estructura organizada: Divide tu código en secciones y utiliza encabezados de comentarios para indicar la función de cada sección. Esto facilita la navegación y la comprensión del código.

// Configuración de la aplicación
const config = {
    // ...
};

// Funciones de utilidad
function utilidad1() {
    // ...
}

// Lógica principal
function logicaPrincipal() {
    // ...
}

6. Ejemplos de uso: Proporciona ejemplos de cómo utilizar tus funciones y métodos en la documentación. Esto ayuda a los desarrolladores a comprender mejor cómo se deben usar.

/**
 * Divide dos números.
 * @param {number} dividendo - El número que se va a dividir.
 * @param {number} divisor - El número por el cual se va a dividir.
 * @returns {number} El resultado de la división.
 * @example
 * const resultado = dividir(10, 2);
 * console.log(resultado); // 5
 */
function dividir(dividendo, divisor) {
    return dividendo / divisor;
}

7. Mantén la documentación actualizada: A medida que realices cambios en el código, asegúrate de actualizar la documentación correspondiente para reflejar esos cambios.
8. Herramientas de generación de documentación: Considera el uso de herramientas de generación de documentación como JSDoc, que pueden ayudarte a crear documentación coherente y legible a partir de tus comentarios.

¿Dónde puedo leer más sobre documentación de código siguiendo los estándares?

1. JSDoc Official Documentation:
   • JSDoc: La documentación oficial de JSDoc es un estándar de documentación de JavaScript ampliamente utilizado. Proporciona ejemplos detallados y una guía completa para documentar tu código JavaScript.
2. Mozilla Developer Network (MDN):
   • MDN JavaScript Guide: MDN ofrece una guía detallada sobre JavaScript, que incluye información sobre cómo documentar código JavaScript de manera efectiva.
3. Si necesitas información básica y ejemplos de JavaScript, visita mi Tutorial de JavaScript básico con ejemplos.
4. Google JavaScript Style Guide:
   • Google JavaScript Style Guide: Google ha publicado su guía de estilo para JavaScript, que incluye pautas sobre la documentación de código.
5. Clean Code: A Handbook of Agile Software Craftsmanship:
   • Libro de Robert C. Martin que ofrece consejos sobre cómo escribir código limpio y legible, lo cual está estrechamente relacionado con la documentación adecuada.
6. Effective JavaScript: 68 Specific Ways to Harness the Power of JavaScript:
   • Este libro de David Herman aborda buenas prácticas en JavaScript, incluida la documentación.
7. Comunidades y foros:
   • Participar en comunidades en línea como Stack Overflow, GitHub, y Reddit (r/javascript) te permitirá aprender de otros desarrolladores y obtener consejos sobre cómo documentar el código de manera efectiva.
8. Ejemplos de proyectos de código abierto:
   • Analizar el código de proyectos de código abierto bien documentados en plataformas como GitHub puede ayudarte a aprender de ejemplos reales de documentación.

¿Cómo usar JSDoc? Tutorial

JSDoc es una herramienta ampliamente utilizada para documentar código JavaScript de manera estándar. Permite generar documentación legible a partir de los comentarios que incluyes en tu código. A continuación, te guiaré sobre cómo puedes usar JSDoc:

1. Instalación:
   • Antes de usar JSDoc, debes instalarlo. Puedes instalarlo globalmente usando npm (Node Package Manager) de la siguiente manera:
   Copy codenpm install -g jsdoc
2. Documentación en tus archivos JavaScript:Para documentar tu código JavaScript, debes agregar comentarios especiales que comiencen con /** justo antes de la declaración que deseas documentar tal como hemos visto previamente con los @param y @return.
3. Generar documentación:
   • Una vez que hayas documentado tu código con JSDoc, puedes generar la documentación ejecutando el siguiente comando en la terminal:
   jsdoc yourFile.js. Reemplaza yourFile.js con el nombre de tu archivo JavaScript. Esto generará archivos HTML de documentación en un directorio llamado out.
4. Ver y usar la documentación:
   • Abre los archivos HTML generados en el directorio out con tu navegador web. En estos archivos, encontrarás la documentación generada a partir de los comentarios JSDoc, que incluirá información sobre las funciones, parámetros, valores de retorno, etc.
5. Etiquetas JSDoc comunes:
   • JSDoc admite muchas etiquetas para documentar diferentes aspectos de tu código. Aquí hay algunas etiquetas comunes:
   • @param: Documenta los parámetros de una función.
   • @returns: Documenta el valor de retorno de una función.
   • @description: Proporciona una descripción más detallada.
   • @example: Incluye ejemplos de uso.
   • @throws: Documenta excepciones lanzadas por una función.
   • @see: Agrega enlaces a recursos relacionados.

Más detalles en JSDoc.

¿Qué debo poner en el archivo readme?

El archivo README es una parte crucial de cualquier proyecto de software, ya que proporciona información esencial para que los usuarios y otros desarrolladores comprendan y utilicen tu proyecto. Veamos lo que debemos incluir en un archivo README:

1. Título y descripción del proyecto:

• Comienza tu README con un título descriptivo y una breve introducción que explique de qué se trata el proyecto. Esto ayudará a los usuarios a comprender rápidamente su propósito.

2. Instrucciones de instalación:

• Proporciona instrucciones claras y concisas sobre cómo instalar y configurar el proyecto en el entorno del usuario. Esto puede incluir comandos de instalación, requisitos previos y configuraciones necesarias.

3. Ejemplos de uso:

• Muestra ejemplos de cómo utilizar el proyecto en la vida real. Puedes incluir fragmentos de código, comandos de línea de comandos o capturas de pantalla para ilustrar cómo funciona.

4. Documentación:

• Enlaza o incorpora la documentación detallada si está disponible en otro lugar. Esto puede incluir documentos generados automáticamente, como los creados con JSDoc, o documentos en línea.

5. Contribución:

• Explica cómo otros desarrolladores pueden contribuir al proyecto. Incluye directrices para presentar problemas, solicitudes de extracción (pull requests), estándares de codificación y cualquier otra información relevante para colaboradores potenciales.

6. Licencia:

• Indica la licencia bajo la cual se distribuye el proyecto. Asegúrate de que la licencia sea clara y adecuada para tu proyecto.

7. Créditos:

• Agradece a las personas o proyectos que contribuyeron al proyecto. Esto puede incluir a los autores, colaboradores, proyectos de código abierto utilizados, entre otros.

8. Estado del proyecto:

• Si el proyecto está en desarrollo activo, beta o alfa, es útil indicar su estado actual. También puedes proporcionar información sobre la versión actual y cualquier futura hoja de ruta del proyecto.

9. Contacto y soporte:

• Proporciona información de contacto o enlaces a canales de soporte donde los usuarios pueden obtener ayuda en caso de problemas o preguntas.

Cómo escribir un README efectivo:

• Usa un formato limpio y fácil de leer. Utiliza encabezados, listas, fragmentos de código y resalta información importante.
• Mantén el README actualizado a medida que evoluciona el proyecto.
• Sé conciso y evita información innecesaria.
• Utiliza un lenguaje claro y sin jerga.
• Sé amigable y alentador para los usuarios y colaboradores.

Un buen README puede hacer que tu proyecto sea más accesible y atractivo para otros desarrolladores y usuarios, por lo que es importante dedicar tiempo a su creación y mantenimiento. Puedes encontrar ejemplos de READMEs en proyectos de código abierto en GitHub para obtener inspiración sobre cómo escribir el tuyo.

¿Cómo se da formato y edito correctamente el archivo readme.md?

El archivo README.md se formatea utilizando Markdown, que es un lenguaje de marcado ligero y fácil de aprender. Markdown te permite dar formato al texto de manera sencilla y rápida. A continuación, te proporciono una guía básica sobre cómo dar formato y editar correctamente un archivo README.md:

1. Encabezados:

Puedes crear encabezados utilizando uno o más signos “#” al principio de una línea, seguidos de un espacio. Cuantos más signos “#” utilices, más pequeño será el encabezado. Por ejemplo:

# Encabezado de primer nivel 
## Encabezado de segundo nivel 
### Encabezado de tercer nivel

2. Texto en negrita y cursiva:

• Para hacer que un texto esté en negrita, utiliza dos asteriscos o dos guiones bajos alrededor del texto: **texto en negrita** o __texto en negrita__.
• Para hacer que un texto esté en cursiva, utiliza un asterisco o un guion bajo alrededor del texto: *texto en cursiva* o _texto en cursiva_.

3. Listas:

Puedes crear listas ordenadas y no ordenadas.

• Listas no ordenadas se crean utilizando asteriscos, signos de menos o signos más, seguidos de un espacio:

* Elemento 1 
* Elemento 2 
* Elemento 3

• Listas ordenadas se crean utilizando números seguidos de un punto y espacio:

1. Primer elemento 
2. Segundo elemento 
3. Tercer elemento

4. Enlaces:

Puedes crear enlaces de la siguiente manera:

[Texto del enlace](URL del enlace)

Por ejemplo:

[Google](https://www.google.com)

5. Imágenes:

Para insertar imágenes, utiliza un formato similar al de los enlaces, pero precedido de un signo de exclamación:

![Texto alternativo de la imagen](URL de la imagen)

6. Citas:

Puedes crear citas utilizando el signo mayor que (“>”) al principio de una línea:

> Esto es una cita.

7. Código:

Para formatear texto como código, utiliza comillas invertidas (`) para rodearlo. Puedes crear bloques de código utilizando triple comilla invertida (“`):

El comando `npm install` instalará las dependencias.

8. Líneas horizontales:

Puedes crear líneas horizontales utilizando tres o más guiones o asteriscos en una línea separada:

---

9. Tablas:

Puedes crear tablas utilizando barras verticales (|) para separar las columnas y guiones para delimitar la fila de encabezado:

| Encabezado 1 | Encabezado 2 |
|--------------|--------------|
| Celda 1,1    | Celda 1,2    |
| Celda 2,1    | Celda 2,2    |

10. Saltos de línea:

Para forzar un salto de línea, puedes agregar dos espacios al final de una línea.

Este es un texto en una línea.  
Este es un texto en la siguiente línea.

Estos son algunos de los elementos de formato más comunes que puedes utilizar en un archivo README.md. Markdown es un lenguaje versátil, por lo que puedes explorar más opciones y detalles en la documentación oficial de Markdown. Además, puedes ver ejemplos en proyectos de código abierto en GitHub para obtener inspiración sobre cómo dar formato a tus README.md.