Au cours des dernières années, je me suis davantage impliqué dans la documentation. Rédiger un texte explicatif sur le fonctionnement d’un système particulier est généralement assez simple. Dessiner un diagramme qui affichera tous les objets clés et les connexions entre ces objets est également assez simple.
Mais l’aspect le plus problématique est de maintenir cette documentation à jour. Et le texte serait bien, mais les diagrammes... Parce que... toute la documentation est en ligne, c'est-à-dire au format html, le texte est accompagné d'images gif/jpeg/png, qui montrent en réalité les diagrammes. Et les diagrammes sont dessinés dans divers programmes tels que Visio ou des services en ligne à la draw.io. Ensuite, vous exportez le diagramme au format graphique et le joignez au HTML. C'est simple.
Quel est le problème?
Les schémas sont généralement simples. Plus précisément, pas très compliqué. Oui, le nombre d'objets est d'une douzaine ou deux, le nombre de connexions est à peu près le même. Plus des signatures, quelques désignations. Des schémas simples peuvent être décrits avec des mots, mais des schémas trop complexes, euh... (c) "ils ne comprendront pas, monsieur." Il existe de nombreux schémas, des modifications doivent y être apportées périodiquement, épisodiquement, c'est-à-dire constamment, parce que ils suivent le développement de nos produits.
Vous pouvez intégrer le html du service. L'as tu essayé?
Oui bien sûr. Par exemple, j'aime les graphiques de gliffy.com. Mais pour apporter des modifications, vous devez accéder à un service tiers et y apporter des modifications. Et il est plus difficile de déléguer les corrections à un collègue.
Que faire?
Récemment je suis tombé sur un dépôt sur Github dans les recommandations . Diagramme sous forme de code. Ceux. nous décrivons le circuit dont nous avons besoin en js. Nous écrivons ce js directement dans le même code HTML que celui où se trouve l'autre texte de la documentation.
À propos, j'écris de la documentation pas entièrement en HTML. En règle générale, la documentation est un ensemble de fichiers avec du texte markdown, qui est ensuite converti en un site de documentation à part entière par un moteur, par exemple Wintersmith. Ou un système wiki.
Cela s'avère très pratique : nous avons écrit le texte, puis la balise script s'ouvre et le code JS du schéma y est décrit.
Quel est le problème à nouveau?
J'ai aimé ce référentiel, mais ce n'est pas le seul exemple où un diagramme est dessiné à l'aide de code ou d'une représentation textuelle. (À la fin de l'article, il y aura des liens vers des projets et des articles que j'ai recherchés sur le diagramme thématique sous forme de code.)
Et je ne suis pas le seul à éditer la documentation. Parfois, des collègues contribuent également : corrigez un mot, modifiez une description, insérez de nouvelles images.
Par conséquent, j’aimerais voir le diagramme dans un format de texte lisible et compréhensible qui ne nécessiterait pas une longue courbe d’apprentissage. Et à certains endroits, vous pouvez même simplement copier-coller pour accélérer l'ajout d'un nouveau circuit.
Et un autre collègue a noté que le code est bien sûr bon, mais si vous utilisez une structure, tout peut être très strict et expressif.
Par conséquent, j'ai essayé d'imaginer le diagramme comme un ensemble de plusieurs petits tableaux décrivant les nœuds, les connexions, les groupes de nœuds, ainsi que l'emplacement des nœuds. Cela s'est avéré, à mon humble avis, assez pratique, même si, bien sûr, le goût et la couleur...
Comment est-ce un graphique dans un tableau ?
- Chaque nœud est décrit par un identifiant qui identifie le nœud de manière unique.
- Vous pouvez également ajouter une icône au nœud et ajouter une inscription.
- Vous pouvez spécifier une relation entre deux nœuds.
- Pour la communication sur le schéma, vous pouvez définir la couleur et l'inscription.
- La direction de la communication est définie comme allant de la source à la cible. Et la source et la cible sont indiquées par des identifiants de nœud.
- Un ou plusieurs nœuds peuvent être ajoutés à un groupe.
- La relation peut également être précisée à la fois depuis le groupe et vers le groupe.
En utilisant ces règles simples, nous obtenons le diagramme suivant. Juste? Assez.
Et il est décrit par le code js suivant. L'essentiel ici est l'objet elements. Dans quels nœuds sont indiqués - nœuds, arêtes - connexions.
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);
Bien sûr, je n'ai pas imaginé le dessin du circuit moi-même, mais j'ai utilisé la bibliothèque est un outil de visualisation très puissant. Je n'utilise qu'une fraction des possibilités dans ma solution.
D'accord, c'est un exemple simple. Est-ce que ça peut être plus compliqué ?
Oui s'il vous plait. Pour indiquer des positions, nous utilisons des positions, pour indiquer des groupes, nous indiquons une liste de groupes en groupes, et les éléments eux-mêmes ont un attribut de groupe.
Et voici le code :
<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>
D'une part, un tel schéma représente presque quelques écrans de code sur un ordinateur portable, d'autre part, la structure à la json vous permet de remplir toutes les données par analogie, rapidement et vous pouvez les copier-coller.
Pourquoi les positions sont-elles placées séparément des nœuds ?
C'est plus confortable. Nous spécifions d’abord les nœuds. Ensuite, nous pouvons spécifier quelques groupes et les indiquer en nœuds. Ensuite, nous désignons les connexions. Et seulement alors, lorsque les objets principaux et les connexions entre eux sont là, nous prenons en charge l'emplacement de ces objets sur le schéma. Ou vice versa.
Est-ce possible sans postes ?
C'est possible sans postes. Mais ce sera un peu froissé, vous pouvez voir cette option dans les exemples. Cela est dû au fait qu'il existe un algorithme pour localiser les nœuds pour le cytoscape. , qui prend également en compte la présence de groupes. La spécification de positions rend le diagramme plus contrôlable, mais au stade de la première ébauche du diagramme, cela est possible sans positions.
Les positions peuvent également être spécifiées dans le style Battleship. Ceux. un nœud est situé en a1 et l’autre en d5. Il est particulièrement utile que le cytoscape rende les objets sur la toile mobiles, c'est-à-dire nous pouvons les déplacer, voir différentes options de mise en page, puis corriger la disposition des éléments que nous aimons dans le code.
En général, c’est compréhensible. Tu peux aussi essayer ?
Bien entendu, pour créer rapidement des circuits, je me suis confectionné un petit , qui met lui-même à jour le schéma et stocke la dernière version dans le navigateur (dans localStorage).
L'as tu essayé? Vous pouvez maintenant l'ajouter à votre page.
Là encore:
1. Connecter le script
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Ajouter du code au 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. nous éditons le code selon le diagramme dont nous avons besoin (je pense que c'est plus facile que de dessiner un hibou :)
Plus de détails sur sur github.
Le résultat?
J'ai atteint mes objectifs : ajouter des diagrammes en ligne à la documentation, le format est assez simple et compréhensible. Ce n’est pas adapté aux super circuits, mais aux petits circuits qui expliquent la structure des connexions, c’est tout à fait bien. Vous pouvez toujours modifier et modifier rapidement quelque chose au fil du temps. Oui, et les collègues peuvent corriger eux-mêmes quelque chose dans le dock, au moins les légendes des objets, sans formation particulière))
Que peut-on améliorer ?
Il existe bien sûr de nombreuses options ici. Ajoutez des icônes supplémentaires (toutes celles existantes sont ajoutées en ligne au script). Choisissez un ensemble d'icônes plus expressives. Permet de spécifier le style de la ligne de connexion. Ajoutez une image d'arrière-plan.
Qu'en penses-tu?
J'ai déjà plusieurs idées de mise en œuvre dans les numéros, vous pouvez également ajouter la vôtre dans les commentaires.
Ma solution est certainement applicable à une gamme restreinte de problèmes, et peut-être trouverez-vous un outil plus pratique pour dessiner des diagrammes en les codant simplement - comme on dit "montrez-moi votre diagramme sous forme de code".
- (9 types d'éditeur de graphiques en ligne)
- Et si vous aimez les diagrammes super détaillés et complexes, alors vous admirerez certainement ce projet :
Source: habr.com