Contenido verificado asociado a este RA
Sistemas de Generación de Ayudas y Formatos Habituales
Esta unidad introduce la importancia de la documentación en el desarrollo de software, explorando los diferentes tipos de sistemas de generación de ayudas y los formatos más comunes para su distribución, preparando al alumno para seleccionar la herramienta adecuada según el contexto del proyecto.
Ayudas Sensibles al Contexto y Documentación de la Información Persistente
Esta unidad aborda la creación de ayudas que se adaptan al contexto de uso de la aplicación y la documentación esencial de la estructura de datos persistentes, garantizando que tanto usuarios como desarrolladores puedan comprender y gestionar la información de manera efectiva.
Manuales de Usuario, Guías de Referencia y Tutoriales
Esta unidad se centra en la creación de documentación orientada al usuario final, incluyendo manuales de usuario detallados, guías de referencia concisas y tutoriales prácticos, esenciales para la adopción y el uso efectivo de la aplicación.
Manuales de Instalación, Configuración y Administración
Esta unidad se enfoca en la documentación técnica esencial para la implementación, mantenimiento y gestión de la aplicación, cubriendo los manuales de instalación, configuración y administración, cruciales para el personal técnico y de soporte.
Conceptos clave
Help Authoring Tool (HAT)Single Source PublishingHTML Help (CHM)Web HelpPDFMarkdownJavadoc/DoxygenAyuda Sensible al ContextoHelp IDAPI de AyudaDiagrama Entidad-Relación (ERD)Diccionario de DatosEspecificación OpenAPI/SwaggerManual de UsuarioGuía de ReferenciaTutorialCapturas de PantallaOrientación a Tareas
Errores que conviene evitar
- No elegir la herramienta adecuada: Causa: Desconocimiento de las opciones o subestimación de la complejidad. Corrección: Evaluar las necesidades del proyecto (escalabilidad, formatos de salida, colaboración) antes de seleccionar la herramienta.
- Generar un único formato para todos los públicos: Causa: Falta de análisis de las necesidades del usuario. Corrección: Identificar los diferentes perfiles de usuario y sus preferencias de acceso a la información.
- Ayuda contextual genérica o incorrecta: Causa: Mapeo incorrecto de IDs o falta de granularidad en los temas de ayuda. Corrección: Realizar pruebas exhaustivas de la ayuda contextual y asegurar que cada Help ID apunte al tema más específico y útil.
- Documentación de datos desactualizada: Causa: Falta de un proceso de actualización de la documentación o de herramientas que generen documentación a partir del esquema real. Corrección: Integrar la generación de documentación de datos en el pipeline de desarrollo y establecer revisiones periódicas.
- Manual de usuario demasiado técnico o con jerga: Causa: El autor de la documentación es un desarrollador que no adapta el lenguaje al público. Corrección: Realizar pruebas de usabilidad con usuarios reales y pedir a personas no técnicas que revisen el manual.
- Tutoriales demasiado largos o con demasiada información: Causa: Intentar cubrir demasiadas funcionalidades en un solo tutorial. Corrección: Dividir los tutoriales en módulos pequeños y enfocados, cada uno con un objetivo de aprendizaje claro.
- Manuales técnicos incompletos o desactualizados: Causa: Falta de rigor en el proceso de documentación o no se actualiza la documentación con cada cambio en el software. Corrección: Establecer un proceso de revisión y actualización de la documentación técnica en cada ciclo de desarrollo, y realizar pruebas de instalación/configuración siguiendo solo el manual.
- Asumir conocimientos del lector: Causa: El autor tiene un conocimiento profundo y olvida que el lector puede no tenerlo. Corrección: Pedir a un técnico con menos experiencia que siga los manuales y anote cualquier ambigüedad o paso faltante.