Smart Engineering Documentation

Smart Engineering Documentation es una función poderosa que genera automáticamente documentación técnica completa para su base de código. Al analizar su código fuente, crea documentación detallada que incluye diagramas de arquitectura, referencias de API y explicaciones de lógica de negocio.

Descripción General

El menú de Smart Engineering Documentation proporciona un flujo de trabajo completo para:

• Crear Proyectos - Configurar nuevos proyectos de documentación para sus bases de código
• Gestionar Organizaciones - Trabajar con múltiples organizaciones y sus proyectos
• Generar Documentación - Crear automáticamente documentación técnica completa
• Gestionar Tareas - Rastrear y regenerar tareas de documentación
• Descargar Artefactos - Exportar documentación en varios formatos

consejo

Acceda a Smart Engineering Documentation desde la barra lateral de AI Cockpit para comenzar a generar documentación profesional para sus proyectos.

Primeros Pasos

Selección de Organización

Antes de crear o gestionar proyectos, debe seleccionar una organización:

1. Abra el menú de Smart Engineering Documentation
2. Use el menú desplegable Selector de Organización en la parte superior
3. Seleccione su organización de la lista
4. Todos los proyectos se filtrarán por la organización seleccionada

info

El selector de organización conserva su elección entre sesiones. Los proyectos siempre están asociados con una organización específica.

Crear un Nuevo Proyecto

Paso 1: Información del Proyecto

Para crear un nuevo proyecto de documentación:

1. Ingrese un Nombre de Proyecto (requerido)

   • Use un nombre descriptivo que identifique su base de código
   • Ejemplo: "API Backend de E-commerce"

2. Agregue una Descripción del Proyecto (opcional)

   • Proporcione contexto sobre el proyecto
   • Incluya tecnologías o frameworks clave utilizados
   • Ejemplo: "API REST de Node.js para plataforma de e-commerce con MongoDB"

3. Haga clic en Crear Proyecto para continuar

advertencia

Asegúrese de haber seleccionado la organización correcta antes de crear un proyecto, ya que esto no se puede cambiar después.

Paso 2: Cargar Código Fuente

Después de crear el proyecto, necesita cargar su código fuente. Hay dos métodos:

Carga de Archivo ZIP

Cargar un Archivo ZIP:

1. Haga clic en Elegir Archivo o arrastre y suelte
2. Seleccione un archivo .zip que contenga su código fuente
3. Asegúrese de que el ZIP incluya todos los archivos fuente relevantes
4. Haga clic en Cargar para iniciar el procesamiento

Mejores Prácticas

• Incluya todos los archivos de código fuente
• Excluya node_modules, vendor u otros directorios de dependencias similares
• Mantenga el archivo ZIP por debajo de 100MB para un procesamiento óptimo
• Incluya archivos de configuración y documentación

Indexación del Espacio de Trabajo

Indexar el Espacio de Trabajo Actual:

1. Haga clic en el botón Indexar Espacio de Trabajo
2. El sistema creará automáticamente un ZIP desde su espacio de trabajo de VSCode abierto
3. Los archivos que coincidan con los patrones .gitignore serán excluidos
4. La carga comienza automáticamente después de la creación del ZIP

info

La indexación del espacio de trabajo respeta su archivo .gitignore y excluye automáticamente los artefactos de compilación comunes y las dependencias.

Paso 3: Generación Automática de Documentación

Una vez que se carga el código fuente:

1. El estado del proyecto cambia a Procesando
2. El sistema analiza la estructura de su base de código
3. Cuando está listo, la generación de Documentación Completa comienza automáticamente
4. Se abre una página de progreso detallada que muestra los pasos de generación

nota

El tiempo de procesamiento inicial depende del tamaño de su base de código. Los proyectos pequeños (< 1000 archivos) generalmente se completan en 2-5 minutos.

Gestión de Proyectos Existentes

Lista de Proyectos

La sección Proyectos Existentes muestra todos los proyectos de la organización seleccionada:

Columna	Descripción
Nombre del Proyecto	El nombre del proyecto
Estado	Estado actual del proyecto (Listo, Procesando, Fallido)
Tareas	Lista de tareas de documentación para el proyecto
Acciones	Operaciones disponibles para el proyecto

Acciones del Proyecto

Cada tarjeta de proyecto proporciona varias acciones:

Ver Detalles

Haga clic en Ver Detalles para abrir una página detallada que muestra:

• Información y metadatos del proyecto
• Historial completo de tareas
• Progreso de generación y registros
• Mensajes de error (si los hay)

Generar Documentación Completa

Disponible cuando:

• El estado del proyecto es Listo
• Aún no existe ninguna tarea de documentación

Al hacer clic en este botón:

1. Inicia una nueva tarea de generación de documentación completa
2. Abre la página de detalles de la tarea automáticamente
3. Muestra actualizaciones de progreso en tiempo real

Regenerar Tarea

Disponible para tareas existentes. Esta acción:

• Crea una nueva tarea de generación de documentación
• Usa el mismo código fuente
• Aplica la configuración actual del LLM
• Abre la página de detalles de la tarea para monitoreo

Cuándo Regenerar

Regenere la documentación cuando:

• Ha actualizado la configuración de su modelo LLM
• La generación anterior tuvo errores
• Desea mejorar la calidad de la documentación
• El análisis del código fuente necesita actualización

Generar Artefactos

Disponible cuando:

• El estado del proyecto es Listo
• La tarea de documentación completa está Completada

Esto genera artefactos descargables que incluyen:

• Documentación Markdown - Documentación completa en formato MD
• Documentación HTML - Versión HTML interactiva
• Diagramas - Diagramas de arquitectura y flujo

Descargar Artefactos

Una vez que se generan los artefactos:

1. Haga clic en el botón Descargar
2. Los artefactos se abren automáticamente en VSCode
3. Los archivos se guardan en su disco local
4. La documentación HTML se puede ver en el navegador

info

Los artefactos descargados incluyen un archivo index.html que proporciona un sitio web de documentación navegable.

Recargar Código Fuente

Para actualizar el proyecto con nuevo código fuente:

1. Haga clic en el botón Recargar
2. Seleccione un nuevo archivo ZIP o indexe el espacio de trabajo
3. El estado del proyecto cambia a Procesando
4. Después de que se complete el procesamiento, la documentación se regenera automáticamente
5. La página de detalles de la tarea se abre para monitoreo

advertencia

Recargar el código fuente reemplazará la base de código existente. Las tareas de documentación anteriores permanecen disponibles como referencia.

Eliminar Proyecto

Para eliminar un proyecto:

1. Haga clic en el botón Eliminar
2. Confirme la eliminación
3. Se eliminan todas las tareas y artefactos asociados

peligro

La eliminación del proyecto es permanente y no se puede deshacer. Descargue cualquier artefacto importante antes de eliminar.

Gestión de Tareas

Lista de Tareas

Cada proyecto puede tener múltiples tareas de documentación:

• Documentación Completa - Documentación completa de la base de código
• Docs - Solo documentación de API y código
• Backlog - Extracción de historias de usuario y requisitos

Estado de las Tareas

Las tareas pueden tener los siguientes estados:

Estado	Descripción	Acciones Disponibles
En Ejecución	La tarea está procesándose actualmente	Ver Detalles
Completada	La tarea finalizó correctamente	Ver Detalles, Generar Artefactos, Descargar
Fallida	La tarea encontró un error	Ver Detalles, Regenerar
No Encontrada	La tarea expiró o fue eliminada	Regenerar

Acciones de Tareas

Ver Detalles de la Tarea

Abre una página detallada que muestra:

• Porcentaje de progreso actual
• Registro de ejecución paso a paso
• Etapas de procesamiento y subpasos
• Mensajes de error (si falló)
• Tiempo estimado de finalización

Regenerar Tarea

Crea una nueva tarea con la misma configuración:

1. Haga clic en Regenerar en la tarea
2. La nueva tarea comienza inmediatamente
3. La página de detalles de la tarea se abre automáticamente
4. La tarea anterior permanece en el historial

Eliminar Tarea

Eliminar una tarea del proyecto:

1. Haga clic en Eliminar en la tarea
2. Confirme la eliminación
3. La tarea y sus artefactos se eliminan

nota

No puede eliminar una tarea que esté en ejecución actualmente. Espere a que se complete o falle antes de eliminar.

Proceso de Generación de Documentación

Etapas de Generación

El proceso de generación de documentación incluye varias etapas:

1. Análisis de Código

   • Análisis de archivos fuente
   • Identificación de la estructura del código
   • Extracción de dependencias

2. Extracción de Símbolos

   • Clases e interfaces
   • Funciones y métodos
   • Variables y constantes

3. Generación de Documentación

   • Documentación de API
   • Descripciones de arquitectura
   • Explicaciones de lógica de negocio

4. Creación de Diagramas

   • Diagramas de arquitectura
   • Diagramas de flujo
   • Gráficos de dependencias

5. Compilación de Artefactos

   • Archivos Markdown
   • Generación de HTML
   • Empaquetado de activos

Monitoreo del Progreso

Mientras se genera la documentación:

• Porcentaje de progreso en tiempo real
• Etapa actual y subpaso
• Tiempo estimado restante
• Registros de ejecución detallados

consejo

Mantenga abierta la página de detalles de la tarea para monitorear el progreso. La página se actualiza automáticamente cada 15 segundos.

Mejores Prácticas

Organización del Proyecto

• ✅ Use nombres de proyecto descriptivos
• ✅ Incluya descripciones completas
• ✅ Agrupe proyectos relacionados por organización
• ✅ Mantenga un proyecto por base de código
• ✅ Actualice el código fuente regularmente

Preparación del Código Fuente

• ✅ Incluya todos los archivos fuente relevantes
• ✅ Excluya los directorios de dependencias
• ✅ Mantenga los archivos ZIP por debajo de 100MB
• ✅ Incluya archivos README y de configuración
• ✅ Asegúrese de que el código esté bien estructurado

Gestión de Documentación

• ✅ Regenere después de cambios significativos en el código
• ✅ Descargue artefactos para acceso sin conexión
• ✅ Revise la documentación generada para verificar su precisión
• ✅ Use los últimos modelos LLM para obtener mejores resultados
• ✅ Mantenga el historial de tareas como referencia

Optimización del Rendimiento

• ✅ Elimine archivos innecesarios antes de cargar
• ✅ Use la indexación del espacio de trabajo para proyectos activos
• ✅ Genere artefactos solo cuando sea necesario
• ✅ Elimine proyectos antiguos para ahorrar espacio
• ✅ Monitoree el progreso de las tareas regularmente

Solución de Problemas

Procesamiento del Proyecto Fallido

Si el procesamiento del proyecto falla:

1. Verifique los detalles del proyecto para ver los mensajes de error
2. Verifique que el archivo ZIP contenga código fuente válido
3. Asegúrese de que el ZIP no esté dañado
4. Intente recargar con un subconjunto más pequeño de la base de código
5. Contacte al soporte si el problema persiste

Generación de Documentación Fallida

Si la generación de documentación falla:

1. Abra los detalles de la tarea para ver los registros de errores
2. Verifique si la estructura de la base de código es compatible
3. Verifique que la configuración del LLM sea correcta
4. Intente regenerar la tarea
5. Considere usar un modelo LLM diferente

Artefactos No Disponibles

Si no se pueden generar los artefactos:

1. Asegúrese de que la tarea de documentación se haya completado correctamente
2. Verifique que el estado del proyecto sea Listo
3. Verifique que tenga permisos suficientes
4. Intente regenerar la documentación
5. Verifique los mensajes de error en los detalles de la tarea

Problemas de Descarga

Si la descarga de artefactos falla:

1. Verifique su conexión a internet
2. Verifique que la URL de descarga siga siendo válida
3. Intente descargar de nuevo después de unos minutos
4. Verifique el panel de salida de VSCode para ver los errores
5. Asegúrese de tener permisos de escritura en la ubicación de descarga

Funciones Avanzadas

Múltiples Organizaciones

Trabaje con múltiples organizaciones:

• Cambie entre organizaciones usando el selector
• Cada organización tiene su propia lista de proyectos
• Los proyectos están aislados por organización
• Los permisos son específicos de la organización

Historial de Tareas

Acceda al historial completo de tareas:

• Vea todas las generaciones de documentación anteriores
• Compare los resultados de diferentes tareas
• Rastree la evolución de la documentación
• Audite los intentos de generación

Configuración Personalizada de LLM

Configure los ajustes del LLM para la documentación:

• Elija diferentes modelos de IA
• Ajuste el idioma de salida
• Personalice los parámetros de generación
• Optimice para casos de uso específicos

Próximos Pasos

Ahora que comprende Smart Engineering Documentation, explore:

• Modos Personalizados - Cree modos de documentación especializados
• Gestión de Configuraciones - Configure las preferencias de LLM y salida
• MarketPlace - Descubra herramientas de documentación adicionales