Tecnología · I Medio

Ideas de aprendizaje activo

Documentación Técnica y de Usuario

La documentación técnica y de usuario requiere práctica activa porque los estudiantes deben experimentar las dificultades de comunicar ideas complejas de manera clara. Al escribir manuales, explicar código o revisar documentos, los estudiantes identifican brechas en su comprensión y mejoran su capacidad para anticipar las necesidades de otros, habilidades clave en innovación tecnológica.

• Objetivos de Aprendizaje (OA)
• OA TEC 1oM: Comunicación y Presentación de Resultados

• 20–45 min
• Parejas → Toda la clase
• 4 actividades

Actividad 01

• Enseñanza entre Pares
• 30 min · Parejas

Enseñanza entre Pares: Creación de Manual de Usuario

En pares, los estudiantes redactan un manual con introducción, pasos numerados, capturas de pantalla y sección de errores comunes para su app. Intercambian con otra pareja para probarlo y anotar mejoras. Discuten ajustes en 5 minutos finales.

¿Qué elementos son esenciales en la documentación técnica de un proyecto de software?

Consejo de Facilitación

Durante la creación de manuales en pares, pida a los estudiantes que intercambien sus borradores y sigan los pasos exactamente como están escritos para identificar confusiones reales.

Qué observar

Los estudiantes intercambian borradores de sus manuales de usuario. Deben verificar si los pasos son lógicos, si las capturas de pantalla son claras y si el lenguaje es accesible para alguien sin experiencia técnica. Cada revisor debe escribir dos sugerencias de mejora específicas.

• Comprender
• Aplicar
• Analizar
• Crear
• Autogestión
• Habilidades de Relación

Actividad 02

• Escritura RAFT
• 45 min · Grupos pequeños

Grupos Pequeños: Documentación de Código

Grupos de 4 documentan funciones clave con comentarios en código, diagramas de flujo y explicaciones. Usan plantillas compartidas en Google Docs. Presentan a la clase un ejemplo y responden preguntas.

¿Cómo se adapta la documentación para diferentes audiencias (desarrolladores vs. usuarios finales)?

Consejo de Facilitación

En la documentación de código en grupos pequeños, exija que cada comentario responda a la pregunta: '¿Qué haría un nuevo desarrollador si yo no estuviera disponible?'

Qué observar

Entregue a cada estudiante una tarjeta con el nombre de un tipo de documento (ej. 'Diagrama de Flujo', 'Glosario', 'Manual de Usuario'). Pida que escriban una oración explicando para qué audiencia principal está diseñado y un elemento clave que debe incluir.

• Aplicar
• Analizar
• Crear
• Conciencia Social
• Autoconciencia

Actividad 03

• Escritura RAFT
• 40 min · Toda la clase

Clase Completa: Revisión Peer de Docs

Todos suben su documentación a una plataforma compartida. En ronda, cada grupo revisa dos docs ajenas con checklist: claridad, completitud, audiencia. Votan mejoras y aplican sugerencias en tiempo real.

¿Por qué es importante mantener la documentación actualizada a lo largo del ciclo de vida del proyecto?

Consejo de Facilitación

En la revisión peer de documentos, asigne roles específicos (ej. revisor técnico, revisor de usuario final) para que evalúen la documentación desde perspectivas distintas.

Qué observar

Presente un fragmento de código sin comentarios y un diagrama de flujo incompleto. Pregunte a los estudiantes: '¿Qué información falta para que un nuevo desarrollador entienda este código?' y '¿Qué paso falta en este diagrama para completar el proceso?'

• Aplicar
• Analizar
• Crear
• Conciencia Social
• Autoconciencia

Actividad 04

• Escritura RAFT
• 20 min · Individual

Individual: Actualización de Documentos

Cada estudiante revisa su doc inicial tras cambios en la app, agrega secciones nuevas y elimina obsoletas. Comparte versión final con profesor para validación rápida.

¿Qué elementos son esenciales en la documentación técnica de un proyecto de software?

Consejo de Facilitación

En la actualización individual de documentos, pida a los estudiantes que registren en una tabla qué cambios hicieron y por qué, fomentando la reflexión sobre el proceso.

Qué observar

Los estudiantes intercambian borradores de sus manuales de usuario. Deben verificar si los pasos son lógicos, si las capturas de pantalla son claras y si el lenguaje es accesible para alguien sin experiencia técnica. Cada revisor debe escribir dos sugerencias de mejora específicas.

• Aplicar
• Analizar
• Crear
• Conciencia Social
• Autoconciencia

Algunas notas para enseñar esta unidad

Enseñamos documentación técnica con un enfoque basado en errores: primero mostramos ejemplos pobres y pedimos a los estudiantes que identifiquen qué falta o está mal. Luego, comparamos sus hallazgos con estándares reconocidos como ISO/IEC 26514 para manuales de usuario. Evitamos asumir que los estudiantes entienden automáticamente la importancia de la audiencia; usamos actividades donde deben adaptar el mismo contenido para diferentes receptores, como desarrolladores versus usuarios finales. La investigación muestra que la documentación mejora cuando se escribe para alguien específico, no para 'el público en general'.

El éxito se mide cuando los estudiantes producen documentos que otros pueden usar sin ayuda adicional. Esto incluye manuales con pasos verificables, código documentado con comentarios relevantes y diagramas que otros desarrolladores entiendan sin explicación oral. La claridad y precisión en las entregas reflejan aprendizaje auténtico.

---

Cuidado con estas ideas erróneas

• During Creación de Manual de Usuario en pares, algunos estudiantes pueden asumir que el manual solo sirve para expertos.

  Durante Creación de Manual de Usuario en pares, entregue a cada estudiante un perfil de usuario ficticio (ej. 'Persona de 50 años sin experiencia en apps') y pídales que adapten el lenguaje y pasos a esa audiencia. Luego, en la revisión entre pares, cada uno debe probar que un compañero que encaje con el perfil pueda completar la tarea usando solo el manual.

• During Documentación de Código en grupos pequeños, algunos creen que una vez escrita la documentación, no necesita revisión.

  Durante Documentación de Código en grupos pequeños, intercambie los documentos entre grupos y pida que identifiquen: 1) qué parte del código no está clara y 2) qué información adicional necesitarían para mantenerlo. Usando la misma función, pero con documentación distinta, los estudiantes ven cómo un error pequeño puede generar grandes problemas.

• During Revisión Peer de Docs en clase completa, algunos piensan que más texto hace mejor la documentación.

  Durante Revisión Peer de Docs en clase completa, use un timer de 3 minutos por documento revisado. Pida a los estudiantes que identifiquen la idea principal de cada sección en una frase y que propongan cómo resumirla aún más. Esto fuerza la concisión y muestra que el exceso de texto confunde más que ayuda.

---

Metodologías usadas en este resumen

• Enseñanza entre Pares
• Escritura RAFT