Diagramas de sirenas

El diagrama de la sirena lleva la creación de diagramas nativos directamente al editor. Impulsado por Mermaid.js, te permite escribir sintaxis de diagramas basados en texto y ver un diagrama visual renderizado en tiempo real, todo ello sin salir de tu espacio de trabajo de documentación. Los diagramas se almacenan como código fuente editable junto a una imagen renderizada. Esto significa que tus diagramas siempre se pueden volver a editar y nunca se convierten en capturas de pantalla estáticas y obsoletas.

¿Qué es Mermaid.js?

Mermaid.js es una biblioteca de diagramas de código abierto que convierte la sintaxis del texto plano en diagramas visuales. En lugar de dibujar las formas manualmente en una herramienta separada, describes el diagrama en texto y la Sirena lo renderiza. Document360 Mermaid.js incrusta directamente en el editor, así que todo el flujo de trabajo ocurre sin salir de tu artículo.

Ejemplo: Las siguientes cuatro líneas de texto producen un diagrama de flujo completo:

graph TD
  A[User submits ticket] --> B{Priority?}
  B -- High --> C[Notify on-call team]
  B -- Low  --> D[Add to backlog]

Cuándo usar diagramas de sirenas

Utiliza diagramas de sirenas cuando tu contenido implique un proceso, relación o estructura que sea más difícil de explicar solo con palabras. Algunos escenarios habituales:

• Un redactor técnico documentando un flujo de aprobación o proceso de incorporación
• Un desarrollador o arquitecto que ilustra una interacción de API, arquitectura del sistema o esquema de base de datos
• Un product manager que mapea un recorrido de usuario o visualiza una cronología de proyecto
• Un equipo de soporte que está creando un diagrama de flujo de resolución de problemas o una ruta de escalada

Si te encuentras describiendo una secuencia de pasos o conexiones entre componentes a lo largo de varios párrafos, un diagrama casi siempre lo comunicará más rápido.

Principales beneficios

Insertando un diagrama de sirena

Para insertar un diagrama de sirena en tu artículo:

1. Haz clic dentro del cuerpo del artículo donde quieres que aparezca el diagrama.
2. Escribe / (corte hacia adelante) para activar el menú de comandos de corte.
3. Escribe Sirena para filtrar las sugerencias.
4. Selecciona diagrama de sirena en el desplegable.

Elegir una plantilla

Una vez que activas la inserción del diagrama de la sirena, aparece el modal de selección de plantillas. Aquí es donde eliges el punto de partida para tu diagrama.

• Desde una plantilla — Navega o busca en las 23 plantillas disponibles y luego haz clic en una. El editor comienza con la sintaxis de esa plantilla precargada.
• Desde en blanco — Haz clic en En blanco para abrir el editor con un panel de sintaxis vacío. Úsalo solo si ya conoces la sintaxis de las sirenas.

Elegir una plantilla

1. Explora las 23 cartas plantilla o escribe una palabra clave (por ejemplo, flow, sequence, gantt) en la barra de búsqueda.
2. Haz clic en la plantilla que coincida con lo que quieres crear.
3. El editor comienza con la sintaxis de esa plantilla precargada. Edítalo aún más para que encaje con tu contenido.

Usando un lienzo en blanco

1. Haz clic en la opción En blanco en la cuadrícula de plantillas.
2. El editor comienza con un panel de sintaxis vacío.
3. Escribe tu sintaxis de sirena desde cero.

Escribir y previsualizar tu diagrama

El editor de diagramas de la sirena es un espacio de trabajo de dos paneles. El panel izquierdo es donde escribes la sintaxis de tu sirena. El panel derecho te muestra una vista previa en tiempo real del diagrama mientras escribes.

1. Empieza con una declaración tipo diagrama en la primera línea. Esto le indica a la Sirena qué tipo de diagrama debe renderizar.

   Tipo de diagrama	Primera línea
   Diagrama de flujo (de arriba a abajo)	graph TD
   Diagrama de flujo (de izquierda a derecha)	graph LR
   Diagrama de secuencia	sequenceDiagram
   Diagrama de clases	classDiagram
   Diagrama de Gantt	gantt
   Diagrama de estados	stateDiagram-v2
   Diagrama entidad-relación	erDiagram
   Gráfico circular	pie
   Mapa mental	mindmap

2. Añade nodos, conexiones y etiquetas en las siguientes líneas. Cada línea que escribes actualiza inmediatamente la vista previa a la derecha.

3. Si trabajas desde una plantilla, simplemente reemplaza el texto provisional por tus propias etiquetas y conexiones.

Si tu sintaxis tiene líneas muy largas (por ejemplo, etiquetas de nodos largas o descripciones detalladas de los bordes), haz clic en el interruptor Envuelto el código debajo del panel de sintaxis para envolver líneas largas dentro del ancho visible del editor. Esto no afecta a la salida del diagrama: solo cambia cómo aparece el código en el editor.

Controles de vista previa

El panel derecho se actualiza al instante mientras escribes. Usa los controles de vista previa para inspeccionar tu diagrama antes de insertarlo.

Hacer zoom in / Zoom out — Haz clic en los botones de zoom in (+) o zoom out (−) para aumentar o disminuir la ampliación de la vista previa. Utilízalo para inspeccionar partes específicas de un diagrama complejo sin afectar al tamaño real del diagrama en el artículo.

Ajustar a pantalla — Haz clic en el icono de ajustar a pantalla ( ) para restablecer el nivel de zoom y así ver todo el diagrama en la zona de vista previa sin necesidad de desplazarte. Usa esto para una revisión final antes de insertarlo.

Expandir / Colapsar — Haz clic en el icono de expandir ( ) en la barra de herramientas del panel de vista previa para ocultar el editor de sintaxis y expande la vista previa para llenar todo el ancho modal. Haz clic en el icono de colapso ( ) para volver a la vista de panel dividido y continuar editando.

Manejo de errores de sintaxis

Si tu sintaxis no es válida, la vista previa muestra un error y el botón Insertar está desactivado.

1. Lee el mensaje de error. Incluye el número de línea que causa el problema.
2. Corrige esa línea en el panel de sintaxis.
3. La vista previa se actualiza automáticamente. Una vez que es válido, el botón Insertar se activa.

Errores y correcciones comunes

:::(Precaución) (

Insertar el diagrama en el artículo

Una vez que la vista previa esté correcta y libre de errores, haz clic en Insertar. Document360 convierte el diagrama en una imagen SVG y lo coloca en la posición del cursor.

Se guardan dos cosas para cada diagrama:

• La imagen de SVG renderizada — visible en el artículo y en la web de la KB.
• La sintaxis de la sirena — almacenada de forma privada, usada cuando editas el diagrama más adelante.

Gestión de un diagrama insertado

Haz clic en cualquier diagrama insertado para abrir el menú de burbujas.

Edición de un diagrama existente

Cada diagrama de sirenas que insertes puede editarse en cualquier momento, incluso después de que el artículo haya sido publicado. La sintaxis original siempre se almacena.

1. Haz clic en el diagrama y luego haz clic en Editar diagrama en el menú de burbujas.
2. El editor comienza con la sintaxis almacenada y una vista previa en directo.
3. Haz tus cambios.
4. Haz clic en Actualizar. El diagrama del artículo ha sido reemplazado; se conservan la posición y la alineación.

Si haces clic en Cancelar o (X) tras hacer cambios, aparece un cuadro de confirmación. Haz clic en Sí, descartar para salir sin guardar, o No, volver atrás para continuar editando.

Cómo ven los lectores tus diagramas

En la página de la base de conocimiento, los diagramas aparecen como imágenes SVG estáticas incrustadas en el artículo. Los lectores pueden hacer clic en cualquier diagrama para abrir una superposición a pantalla completa, lo cual es útil para diagramas grandes o complejos. Los controles de edición y la sintaxis fuente nunca se exponen a los lectores.

Mejores prácticas

• Un diagrama, una idea. Si un diagrama de flujo supera los 15–20 nodos, divídelo en un diagrama general y un diagrama de detalle.
• Siempre añade un pie de foto. Usa la opción de pie de foto en el menú de burbujas para etiquetar cada diagrama. Ayuda a los lectores a entender el contexto de un vistazo.
• Usa SVG para uso externo. SVG es infinitamente escalable sin pérdida de calidad. Usa PNG solo cuando la herramienta de destino no soporte SVG.
• Copiar para duplicar, no para reconstruir. Usa la acción de menú Copiar burbuja para duplicar un diagrama. Cada copia tiene una sintaxis independiente: editar una no afecta a la otra. Pegar un diagrama de la sirena fuera de Document360 (por ejemplo, en otra herramienta) solo pegará la imagen, no la sintaxis fuente.

Plantillas disponibles

Las siguientes plantillas están disponibles en la pantalla de Selección de Plantillas. Busca por nombre o palabra clave para encontrar la adecuada rápidamente.

Preguntas frecuentes