Saltar a contenido

Herramientas para documentar

En este proyecto utilizaremos dos herramientas clave para la documentación, cada una con un propósito claro:

  • Wiki del repositorio: Para documentar procesos, aprendizajes y cualquier información relacionada con la gestión del proyecto.
  • JSDoc: Para documentar el código de forma profesional, generando documentación automáticamente.

Wiki del repositorio

La Wiki de GitHub es ideal para organizar información que no está directamente relacionada con el código. Es independiente de los archivos del repositorio, cuenta con historial de revisiones para cada página y facilita la colaboración en equipo.

¿Qué documentaremos?

  • Scrum: Página principal con subpáginas para roles, reuniones y Sprints.

  • Formación: Páginas para cada tecnología del stack MERN, con resúmenes de lo aprendido.

  • Proyecto: Información técnica, decisiones importantes y notas clave.

Ejemplo de estructura

  1. Scrum

    • Roles.
    • Ciclo del Sprint.
    • Registro de reuniones.

  2. Formación

    • MongoDB.
    • Node.js.
    • Express.
    • React.
    • Retos prácticos.

  3. Proyecto

    • Configuraciones iniciales.
    • Estructura del backend y frontend.
    • Notas técnicas relevantes.

Recursos para aprender a usar la wiki

JSDoc

JSDoc es una herramienta esencial para documentar funciones, métodos y estructuras de datos en el código. Los comentarios de JSDoc permiten generar documentación completa y exportable al final del proyecto, manteniendo el código autoexplicado durante todo el desarrollo.

¿Qué documentaremos?

  • Funciones del backend y frontend.
  • Parámetros y valores devueltos.
  • Métodos específicos utilizados en el proyecto.

Ejemplo de uso

/**
 * Calcula el descuento aplicado a un precio.
 * @param {number} precio - El precio original.
 * @param {number} descuento - Porcentaje de descuento (0-100).
 * @returns {number} El precio con descuento aplicado.
 */
function calcularDescuento(precio, descuento) {
  return precio - (precio * (descuento / 100));
}

Recursos para aprender a usar JsDoc

Retos prácticos

Reto 1: Configurar la Wiki del repositorio

  • Crea una página principal llamada Documentación del proyecto.

  • Añade subpáginas organizadas en tres secciones principales:

    • Scrum: Roles, reuniones, y registro de Sprints.
    • Formación: Una página por cada tecnología (MongoDB, Node.js, Express, React), y otra para los retos prácticos que se proponen.
    • Proyecto: Notas técnicas, estructura del backend y frontend.

Documenta:

  • La estructura creada en la Wiki.
  • Ejemplos iniciales o notas básicas en cada subpágina.

Reto 2: Documentar el Sprint 1 en la Wiki

  1. Crea una subpágina en la sección Scrum llamada Sprint 1.

  2. En esta página, incluye:

    • Objetivo del Sprint: Lo que esperan lograr durante este ciclo.
    • Roles: Scrum Master, Product Owner, y equipo de desarrollo asignados.
    • Tareas del Sprint: Copia la planificación realizada en GitHub Projects.

Ejemplo de formato:

### Objetivo del Sprint
Familiarizarse con las tecnologías del stack MERN.

### Roles
- **Scrum Master:** Ana
- **Product Owner:** Luis
- **Equipo de desarrollo:** Todos

### Tareas del Sprint
| Tarea                   | Responsable | Estado     | Prioridad |
|-------------------------|-------------|------------|-----------|
| Configurar MongoDB Atlas | Luis        | Por hacer  | 1         |
| Crear servidor Express  | Ana         | Por hacer  | 2         |

Reto 3: Crear ejemplos con JSDoc

Escribe una función en Node.js que convierta una cantidad de días en horas:

  • Función: convertirDiasAHoras(dias)
  • Parámetro: dias (número de días).
  • Retorna: Número de horas.

Documenta esta función utilizando JSDoc:

/**
 * Convierte una cantidad de días en horas.
 * @param {number} dias - Número de días a convertir.
 * @returns {number} Número de horas equivalentes.
 */
function convertirDiasAHoras(dias) {
  return dias * 24;
}

Documentación obligatoria: Todos los retos y su resolución deben estar documentados en la Wiki.

Consejos finales

  • Wiki: Organiza la información en páginas y subpáginas claras. Usa títulos descriptivos para facilitar el acceso.

  • JSDoc: Asegúrate de documentar las funciones a medida que las desarrollas para evitar trabajo acumulado.

  • Revisión continua: Tanto la Wiki como el código deben mantenerse actualizados durante todo el proyecto.

Una buena documentación no solo mejora tu proyecto actual, sino que también te prepara para proyectos futuros y trabajo en equipo.