In den letzten Jahren habe ich mich immer mehr mit der Dokumentation beschäftigt. Einen erläuternden Text über die Funktionsweise eines bestimmten Systems zu verfassen, ist im Allgemeinen recht einfach. Es ist auch ganz einfach, ein Diagramm zu zeichnen, das alle wichtigen Objekte und die Verbindungen zwischen diesen Objekten anzeigt.
Der problematischste Aspekt besteht jedoch darin, diese Dokumentation auf dem neuesten Stand zu halten. Und der Text wäre in Ordnung, aber die Diagramme... Weil... Die gesamte Dokumentation ist online, d. h. im HTML-Format, dann wird der Text von GIF-/JPEG-/PNG-Bildern begleitet, die die Diagramme tatsächlich zeigen. Und Diagramme werden in verschiedenen Programmen wie Visio oder Online-Diensten a la draw.io gezeichnet. Anschließend exportieren Sie das Diagramm in ein Grafikformat und hängen es an HTML an. Es ist einfach.
Was ist das Problem?
Die Schemata sind normalerweise einfach. Genauer gesagt, nicht sehr kompliziert. Ja, die Anzahl der Objekte beträgt ein Dutzend oder zwei, die Anzahl der Verbindungen ist ungefähr gleich. Dazu Unterschriften, einige Bezeichnungen. Einfache Schemata können mit Worten beschrieben werden, aber zu komplexe, ähm ... (c) „Sie werden es nicht verstehen, Sir.“ Es gibt viele Schemata, an ihnen müssen regelmäßig, episodisch, d. h. Änderungen vorgenommen werden. ständig, weil Sie verfolgen die Entwicklung unserer Produkte.
Sie können den HTML-Code des Dienstes einbetten. Hast du es versucht?
Ja natürlich. Mir gefallen zum Beispiel die Grafiken von gliffy.com. Um jedoch Änderungen vorzunehmen, müssen Sie zu einem Drittanbieterdienst gehen und dort Änderungen vornehmen. Und es ist schwieriger, Korrekturen an einen Kollegen zu delegieren.
Was zu tun ist?
Kürzlich bin ich in den Empfehlungen auf ein Repository auf Github gestoßen . Diagramm als Code. Diese. Wir beschreiben die Schaltung, die wir brauchen, in js. Wir schreiben dieses JS direkt in denselben HTML-Code, in dem sich der andere Dokumentationstext befindet.
Übrigens schreibe ich Dokumentationen nicht ausschließlich in HTML. In der Regel handelt es sich bei der Dokumentation um eine Reihe von Dateien mit Markdown-Text, die dann von einer Engine, beispielsweise Wintersmith, in eine vollständige Dokumentationsseite umgewandelt werden. Oder ein Wiki-System.
Es stellt sich als sehr praktisch heraus: Wir haben den Text geschrieben, dann öffnet sich das Skript-Tag und der JS-Code des Schemas wird darin beschrieben.
Was ist nochmal los?
Mir gefiel dieses Repository, aber dies ist nicht das einzige Beispiel, bei dem ein Diagramm mithilfe von Code oder einer Textdarstellung gezeichnet wird. (Am Ende des Artikels finden Sie Links zu Projekten und Artikeln, die ich im Themendiagramm als Code gegoogelt habe.)
Und ich bin nicht der Einzige, der die Dokumentation bearbeitet. Manchmal tragen auch Kollegen mit – korrigieren Sie ein Wort, ändern Sie eine Beschreibung, fügen Sie neue Bilder ein.
Daher möchte ich das Diagramm in einem lesbaren, verständlichen Textformat sehen, das keine lange Lernkurve erfordert. Und an manchen Stellen können Sie sogar einfach kopieren und einfügen, um das Hinzufügen einer neuen Schaltung zu beschleunigen.
Und ein anderer Kollege bemerkte, dass Code natürlich gut sei, aber wenn man Struktur verwende, könne alles sehr streng und ausdrucksstark sein.
Daher habe ich versucht, mir das Diagramm als eine Menge mehrerer kleiner Arrays vorzustellen, die Knoten, Verbindungen, Knotengruppen sowie die Position von Knoten beschreiben. Es stellte sich meiner bescheidenen Meinung nach als recht praktisch heraus, obwohl natürlich der Geschmack und die Farbe...
Wie ist das ein Diagramm in einem Array?
- Jeder Knoten wird durch eine Kennung beschrieben, die den Knoten eindeutig identifiziert.
- Sie können dem Knoten auch ein Symbol und eine Beschriftung hinzufügen.
- Sie können eine Beziehung zwischen zwei Knoten angeben.
- Für die Kommunikation im Diagramm können Sie Farbe und Beschriftung festlegen.
- Die Richtung der Kommunikation wird als von der Quelle zum Ziel definiert. Und die Quelle und das Ziel werden durch Knotenkennungen angegeben.
- Einer Gruppe können ein oder mehrere Knoten hinzugefügt werden.
- Die Beziehung kann auch sowohl von der Gruppe als auch zur Gruppe angegeben werden.
Mit diesen einfachen Regeln erhalten wir das folgende Diagramm. Nur? Ganz.
Und es wird durch den folgenden js-Code beschrieben. Die Hauptsache hier ist das Elements-Objekt. In welchen Knoten sind Knoten, Kanten - Verbindungen angegeben.
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);
Die Zeichnung der Schaltung habe ich mir natürlich nicht selbst ausgedacht, sondern die Bibliothek genutzt ist ein sehr leistungsfähiges Visualisierungstool. Ich nutze in meiner Lösung nur einen Bruchteil der Möglichkeiten.
Okay, das ist ein einfaches Beispiel. Kann es komplizierter sein?
Ja, bitte. Um Positionen anzugeben, verwenden wir Positionen, um Gruppen anzugeben, geben wir eine Liste von Gruppen in Gruppen an, und die Elemente selbst haben ein Gruppenattribut.
Und das ist der 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>
Einerseits handelt es sich bei einem solchen Schema fast um ein paar Codebildschirme auf einem Laptop, andererseits ermöglicht die Struktur a la json das analoge, schnelle Ausfüllen aller Daten und das Kopieren und Einfügen.
Warum werden Positionen getrennt von Knoten platziert?
Es ist bequemer. Zuerst geben wir Knoten an. Dann können wir ein paar Gruppen spezifizieren und sie in Knoten angeben. Dann bezeichnen wir die Verbindungen. Und erst dann, wenn die Hauptobjekte und Verbindungen zwischen ihnen vorhanden sind, übernehmen wir die Position dieser Objekte im Diagramm. Oder umgekehrt.
Ist es ohne Positionen möglich?
Es ist ohne Positionen möglich. Es wird aber etwas zerknittert sein; Sie können diese Option in den Beispielen sehen. Dies liegt daran, dass es einen Algorithmus zur Lokalisierung von Knoten für die Zytolandschaft gibt , wobei auch die Anwesenheit von Gruppen berücksichtigt wird. Durch die Angabe von Positionen wird das Diagramm besser kontrollierbar, im Stadium des ersten Entwurfs des Diagramms ist es jedoch auch ohne Positionen möglich.
Positionen können auch im Battleship-Stil angegeben werden. Diese. Ein Knoten befindet sich in a1 und der andere in d5. Besonders hilfreich ist, dass Cytoscape die Objekte auf der Leinwand beweglich macht, d. h. Wir können sie verschieben, verschiedene Layoutoptionen sehen und dann die Anordnung der Elemente im Code festlegen, die uns gefallen.
Im Allgemeinen ist es verständlich. Sie können auch versuchen?
Um schnell Schaltungen erstellen zu können, habe ich mir natürlich eine kleine gemacht , das selbst das Schema aktualisiert und die neueste Version im Browser speichert (in localStorage).
Hast du es versucht? Sie können es jetzt zu Ihrer Seite hinzufügen.
Dann nochmal:
1. Das Skript verbinden
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Fügen Sie Code zu HTML hinzu
<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. Wir bearbeiten den Code in das Diagramm, das wir brauchen (ich denke, es ist einfacher, als eine Eule zu zeichnen :)
Weitere Details unter auf Github.
Das Ergebnis?
Ich habe mein Ziel erreicht – der Dokumentation Inline-Diagramme hinzuzufügen, das Format ist recht einfach und verständlich. Für Superschaltungen ist es nicht geeignet, aber für kleine Schaltungen, die den Aufbau von Verbindungen erklären, völlig in Ordnung. Sie können im Laufe der Zeit immer schnell etwas optimieren und ändern. Ja, und Kollegen können im Dock selbst etwas korrigieren, zumindest Bildunterschriften für Objekte, ohne spezielle Schulung))
Was kann verbessert werden?
Hier gibt es natürlich viele Möglichkeiten. Fügen Sie zusätzliche Symbole hinzu (alle vorhandenen werden inline zum Skript hinzugefügt). Wählen Sie einen ausdrucksstärkeren Satz von Symbolen. Ermöglicht die Angabe des Stils der Verbindungslinie. Fügen Sie ein Hintergrundbild hinzu.
Was denken Sie?
Ich habe bereits mehrere Ideen zur Umsetzung in Ausgaben, Sie können Ihre auch in den Kommentaren hinzufügen.
Meine Lösung ist auf jeden Fall auf einen begrenzten Bereich von Problemen anwendbar, und vielleicht finden Sie ein praktischeres Werkzeug zum Zeichnen von Diagrammen, indem Sie sie einfach codieren – wie es so schön heißt: „Zeigen Sie mir Ihr Diagramm als Code.“
- (Online-Editor für 9 Arten von Diagrammen)
- Und wenn Sie superdetaillierte und komplexe Diagramme mögen, dann werden Sie dieses Projekt auf jeden Fall bewundern:
Source: habr.com