En los últimos años me he involucrado más en la documentación. Escribir un texto explicativo sobre cómo funciona tal o cual sistema suele ser bastante sencillo. Dibujar un diagrama que muestre todos los objetos clave y las conexiones entre estos objetos también es bastante fácil.
Pero el aspecto más problemático es mantener actualizada esta documentación. Y el texto estaría bien, pero los diagramas... Porque... toda la documentación está en línea, es decir. en formato html, luego el texto va acompañado de imágenes gif/jpeg/png, que realmente muestran los diagramas. Y los diagramas se dibujan en varios programas como Visio o servicios en línea a la draw.io. Luego exportas el diagrama a formato gráfico y lo adjuntas a html. Es sencillo.
¿Cuál es el problema?
Los esquemas suelen ser sencillos. Más precisamente, no muy complicado. Sí, la cantidad de objetos es una docena o dos, la cantidad de conexiones es aproximadamente la misma. Además de firmas, algunas designaciones. Los esquemas simples se pueden describir con palabras, pero los demasiado complejos, ejem... (c) “no lo entenderán, señor”. Hay muchos esquemas, es necesario realizar cambios en ellos periódicamente, de forma episódica, es decir, constantemente, porque siguen el desarrollo de nuestros productos.
Puede incrustar el html del servicio. ¿Lo has probado?
Si seguro. Por ejemplo, me gustan los gráficos de gliffy.com. Pero para realizar cambios, debe ir a un servicio de terceros y editar allí. Y es más difícil delegar las correcciones en un colega.
¿Qué hacer?
Recientemente encontré un repositorio en Github en las recomendaciones. . Diagrama como código. Aquellos. Describimos el circuito que necesitamos en js. Escribimos este js directamente en el mismo html donde está el otro texto de documentación.
Por cierto, no escribo documentación enteramente en HTML. Por lo general, la documentación es un conjunto de archivos con texto marcado, que luego algún motor, por ejemplo Wintersmith, convierte en un sitio de documentación completo. O un sistema wiki.
Resulta muy conveniente: hemos escrito el texto, luego se abre la etiqueta script y en ella se describe el código JS del esquema.
¿Qué está mal de nuevo?
Me gustó este repositorio, pero este no es el único ejemplo en el que se dibuja un diagrama usando código o una representación de texto. (Al final del artículo habrá enlaces a proyectos y artículos que busqué en Google en el diagrama de temas como código).
Y no soy el único que edita la documentación. A veces los compañeros también contribuyen: corrigen una palabra, cambian una descripción, insertan nuevas imágenes.
Por lo tanto, me gustaría ver el diagrama en un formato de texto legible y comprensible que no requiera una larga curva de aprendizaje. Y en algunos lugares puedes incluso simplemente copiar y pegar para acelerar la adición de un nuevo circuito.
Y otro colega señaló que el código es, por supuesto, bueno, pero si usas una estructura, todo puede ser muy estricto y expresivo.
Por lo tanto, traté de imaginar el diagrama como un conjunto de varias matrices pequeñas que describen nodos, conexiones, grupos de nodos, así como la ubicación de los nodos. Resultó, en mi humilde opinión, bastante conveniente, aunque, por supuesto, el sabor y el color...
¿Cómo es esto un gráfico en una matriz?
- Cada nodo se describe mediante un identificador que identifica de forma única al nodo.
- También puedes agregar un ícono al nodo y agregar una inscripción.
- Puede especificar una relación entre dos nodos.
- Para la comunicación según el diagrama, puede configurar el color y la inscripción.
- La dirección de la comunicación se define como desde el origen hasta el destino. Y el origen y el destino se indican mediante identificadores de nodo.
- Se pueden agregar uno o más nodos a un grupo.
- La relación también se puede especificar tanto desde el grupo como hacia el grupo.
Usando estas simples reglas, obtenemos el siguiente diagrama. ¿Justo? Bastante.
Y se describe en el siguiente código js. Lo principal aquí es el objeto de elementos. En el que se indican los nodos - nodos, bordes - conexiones.
const elements = {
nodes: [ // описываем узлы
{ id: 'client', type: 'smartphone', label: 'Mobile App'},
{ id: 'server', type: 'server', label: 'Main Server'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [ // указываем связи
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
Por supuesto, no se me ocurrió el dibujo del circuito yo mismo, sino que usé la biblioteca. Es una herramienta de visualización muy poderosa. Solo uso una fracción de las posibilidades en mi solución.
Bien, este es un ejemplo simple. ¿Puede ser más complicado?
Sí, por favor. Para indicar posiciones usamos posiciones, para indicar grupos, indicamos una lista de grupos en grupos, y los elementos en sí tienen un atributo de grupo.
Y este es el código:
<div id="scheme5" style="height:500px;width:800px;"></div>
<script>
const elements5 = {
groups: [
{ id: 'g1', label: 'Группа сервисов 1'},
{ id: 'g2', label: 'Группа сервисов 2'},
],
nodes: [
{ id: 'man1', type: 'person', label: 'Человек'},
{ id: 'client', type: 'smartphone', label: 'Смартфон'},
{ id: 'agent-backend', type: 'server', group: 'g1', label: 'agent-backend'},
{ id: 'web', type: 'server', group: 'g1', label: 'Приложение admin'},
{ id: 'www', type: 'server', group: 'g1', label: 'страница загрузки'},
{ id: 'mongodb1', type: 'database', group: 'g1', label: 'Mongo DB 1'},
{ id: 'mongodb2', type: 'database', group: 'g1', label: 'Mongo DB 2'},
{ id: 'runner-integration1', type: 'worker', group: 'g1', label: 'отправка'},
{ id: 'runner-integration2', type: 'worker', group: 'g1', label: 'отправка'},
{ id: 'api', type: 'server', group: 'g1', label: 'API'},
{ id: 'server2', type: 'server', group:'g2', label: 'сервер'},
{ id: 'otherServer', type: 'server', group:'g2', label: 'сервер'},
{ id: 'firebase', type: 'cloud', label: 'Google Firebase'},
],
edges: [
{ source: 'client', target: 'agent-backend', label: 'json', color: 'red' },
{ source: 'agent-backend', target: 'mongodb1', color: 'red' },
{ source: 'agent-backend', target: 'mongodb2', color: 'red' },
{ source: 'mongodb1', target: 'runner-integration1', label: 'данные' },
{ source: 'mongodb2', target: 'runner-integration2', label: 'данные' },
{ source: 'mongodb1', target: 'web', label: 'данные для отображения' },
{ source: 'runner-integration1', target: 'server2', label: 'данные' },
{ source: 'runner-integration2', target: 'otherServer', label: 'данные' },
{ source: 'api', target: 'firebase', label: 'запросы', color: 'blue', },
{ source: 'firebase', target: 'client', label: 'push', color: 'blue'},
{ source: 'server2', target: 'api', label: 'уведомления', color: 'blue'},
{ source: 'man1', target: 'client', },
],
positions: [
{ id: 'client', row: 2, col: 1,},
{ id: 'agent-backend', row: 2, col: 3,},
{ id: 'web', row: 6, col: 3,},
{ id: 'www', row: 1, col: 3,},
{ id: 'mongodb1', row: 1, col: 4,},
{ id: 'mongodb2', row: 2, col: 5,},
{ id: 'runner-integration1', row: 3, col: 3,},
{ id: 'runner-integration2', row: 4, col: 3,},
{ id: 'api', row: 5, col: 3,},
{ id: 'server2', row: 6, col: 7,},
{ id: 'otherServer', row: 4, col: 7,},
{ id: 'firebase', row: 5, col: 1,},
{ id: 'logger', row: 2, col: 7,},
{ id: 'crm', row: 5, col: 8,},
],
};
Diagram('scheme5', elements5, {layout: 'grid'});
</script>
Por un lado, dicho esquema es casi un par de pantallas de código en una computadora portátil, por otro lado, la estructura a la json le permite completar todos los datos por analogía, rápidamente y puede copiar y pegar.
¿Por qué las posiciones se colocan separadas de los nodos?
Es más cómodo. Primero especificamos los nodos. Luego podemos especificar un par de grupos e indicarlos en nodos. Luego designamos las conexiones. Y solo entonces, cuando los objetos principales y las conexiones entre ellos estén ahí, asumimos la ubicación de estos objetos en el diagrama. O viceversa.
¿Es posible sin puestos?
Es posible sin posiciones. Pero quedará un poco arrugado, puedes ver esta opción en los ejemplos. Esto se debe al hecho de que existe un algoritmo para la ubicación de los nodos para el citoscape. , que también tiene en cuenta la presencia de grupos. Especificar posiciones hace que el diagrama sea más controlable, pero en la etapa del primer borrador del diagrama es posible sin posiciones.
Las posiciones también se pueden especificar en el estilo Acorazado. Aquellos. un nodo está ubicado en a1 y el otro en d5. Ayuda especialmente que Cytoscape haga que los objetos en el lienzo sean móviles, es decir. podemos moverlos, ver diferentes opciones de diseño y luego arreglar la disposición de los elementos que nos gusten en el código.
En general, es comprensible. ¿También puedes intentarlo?
Por supuesto, para crear circuitos rápidamente, me hice un pequeño , que a su vez actualiza el esquema y almacena la última versión en el navegador (en localStorage).
¿Lo has probado? Ahora puedes agregarlo a tu página.
Entonces otra vez:
1. Conectando el guión
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Agregar código a html
<div id="scheme1" style="height:300px;width:800px;"></div>
<script>
const elements = {
nodes: [
{ id: 'client', type: 'smartphone', label: 'Mobile App'},
{ id: 'server', type: 'server', label: 'Main Server'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
</script>
3. editamos el código al diagrama que necesitamos (creo que es más fácil que dibujar un búho :)
Más detalles en en github.
¿El resultado?
Logré mi objetivo: agregar diagramas en línea a la documentación, el formato es bastante simple y comprensible. No es adecuado para supercircuitos, pero para circuitos pequeños que explican la estructura de las conexiones, está absolutamente bien. Siempre puedes modificar y cambiar algo rápidamente con el tiempo. Sí, y los colegas pueden corregir algo ellos mismos en el banquillo, al menos leyendas de objetos, sin una formación especial))
¿Qué se puede mejorar?
Por supuesto, aquí hay muchas opciones. Agregue íconos adicionales (todos los existentes se agregan en línea al script). Elija un conjunto de iconos más expresivo. Permite especificar el estilo de la línea de conexión. Añade una imagen de fondo.
¿Qué piensas?
Ya tengo varias ideas para implementar en los problemas, también puedes agregar la tuya en los comentarios.
Mi solución es definitivamente aplicable a una gama limitada de problemas, y tal vez usted encuentre una herramienta más conveniente para dibujar diagramas simplemente codificándolos, como dicen "muéstreme su diagrama como código".
- (9 tipos de gráficos editor en línea)
- Y si te gustan los diagramas súper detallados y complejos, definitivamente admirarás este proyecto:
Fuente: habr.com