De laatste paar jaar ben ik mij meer met documentatie gaan bezighouden. Het schrijven van een verklarende tekst over hoe dit of dat systeem werkt, is over het algemeen vrij eenvoudig. Het tekenen van een diagram dat alle belangrijke objecten en de verbindingen tussen deze objecten weergeeft, is ook vrij eenvoudig.
Maar het meest problematische aspect is het up-to-date houden van deze documentatie. En de tekst zou prima zijn, maar de diagrammen... Omdat... alle documentatie is online, d.w.z. in html-formaat, dan wordt de tekst vergezeld van gif/jpeg/png-afbeeldingen, die de diagrammen daadwerkelijk tonen. En diagrammen worden getekend in verschillende programma's zoals Visio of online diensten a la draw.io. Vervolgens exporteert u het diagram naar grafisch formaat en voegt u het toe aan HTML. Het is makkelijk.
Wat is het probleem?
De schema's zijn meestal eenvoudig. Om precies te zijn, niet erg ingewikkeld. Ja, het aantal objecten is een tiental of twee, het aantal verbindingen is ongeveer hetzelfde. Plus handtekeningen, enkele aanduidingen. Eenvoudige schema's kunnen in woorden worden beschreven, maar te complexe, ahem... (c) "ze zullen het niet begrijpen, meneer." Er zijn veel schema's, er moeten periodiek, episodisch, wijzigingen in worden aangebracht, d.w.z. voortdurend, omdat zij volgen de ontwikkeling van onze producten.
U kunt de html van de service insluiten. Heb je het geprobeerd?
Ja tuurlijk. Ik vind bijvoorbeeld de graphics van griffy.com leuk. Maar om wijzigingen aan te brengen, moet u naar een service van derden gaan en daar bewerken. En het is lastiger om correcties aan een collega te delegeren.
Wat te doen?
Onlangs kwam ik in de aanbevelingen een repository op Github tegen . Diagram als code. Die. we beschrijven het circuit dat we nodig hebben in js. We schrijven deze js rechtstreeks in dezelfde html waar de andere documentatietekst staat.
Overigens schrijf ik documentatie niet volledig in html. Documentatie bestaat doorgaans uit een reeks bestanden met markdown-tekst, die vervolgens door een bepaalde engine, bijvoorbeeld Wintersmith, wordt omgezet in een volwaardige documentatiesite. Of een wikisysteem.
Het blijkt erg handig: we hebben de tekst geschreven, vervolgens wordt de scripttag geopend en wordt de JS-code van het schema erin beschreven.
Wat is er weer mis?
Ik vond deze repository leuk, maar dit is niet het enige voorbeeld waarin een diagram wordt getekend met behulp van code of een tekstrepresentatie. (Aan het einde van het artikel staan links naar projecten en artikelen die ik als code in het onderwerpdiagram heb gegoogled.)
En ik ben niet de enige die de documentatie redigeert. Soms dragen collega's ook bij: corrigeer een woord, wijzig een beschrijving, voeg nieuwe afbeeldingen in.
Daarom zou ik het diagram graag in een leesbaar, begrijpelijk tekstformaat zien waarvoor geen lange leercurve nodig is. En op sommige plaatsen kun je zelfs eenvoudigweg kopiëren en plakken om het toevoegen van een nieuw circuit te versnellen.
En een andere collega merkte op dat code natuurlijk goed is, maar als je structuur gebruikt, kan alles heel strikt en expressief zijn.
Daarom probeerde ik het diagram voor te stellen als een set van verschillende kleine arrays die knooppunten, verbindingen, groepen knooppunten en de locatie van knooppunten beschrijven. Het bleek naar mijn bescheiden mening best handig, hoewel de smaak en kleur natuurlijk...
Hoe is dit een diagram in een array?
- Elk knooppunt wordt beschreven door een identificatie die het knooppunt op unieke wijze identificeert.
- U kunt ook een pictogram aan het knooppunt toevoegen en een inscriptie toevoegen.
- U kunt een relatie tussen twee knooppunten opgeven.
- Voor communicatie over het diagram kunt u de kleur en opschrift instellen.
- De communicatierichting wordt gedefinieerd als van bron naar doel. En de bron en het doel worden aangegeven door knooppunt-ID's.
- Aan een groep kunnen één of meerdere knooppunten worden toegevoegd.
- Ook kan de relatie zowel vanuit de groep als naar de groep worden gespecificeerd.
Met behulp van deze eenvoudige regels krijgen we het volgende diagram. Zojuist? Nogal.
En het wordt beschreven door de volgende js-code. Het belangrijkste hier is het elementenobject. Waarin knooppunten worden aangegeven - knooppunten, randen - verbindingen.
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);
Natuurlijk heb ik de tekening van het circuit niet zelf bedacht, maar heb ik de bibliotheek gebruikt is een zeer krachtig visualisatiehulpmiddel. Ik gebruik slechts een fractie van de mogelijkheden in mijn oplossing.
Oké, dit is een eenvoudig voorbeeld. Kan het ingewikkelder?
Ja graag. Om posities aan te geven gebruiken we posities, om groepen aan te duiden geven we een lijst met groepen in groepen aan, en de elementen zelf hebben een groepsattribuut.
En dit is de 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>
Aan de ene kant is zo'n schema bijna een paar codeschermen op een laptop, aan de andere kant kun je dankzij de structuur a la json alle gegevens snel naar analogie invullen en kun je kopiëren en plakken.
Waarom worden posities gescheiden van knooppunten geplaatst?
Het is comfortabeler. Eerst specificeren we knooppunten. Vervolgens kunnen we een aantal groepen specificeren en deze in knooppunten aangeven. Vervolgens wijzen we de verbindingen aan. En pas dan, als de hoofdobjecten en de verbindingen ertussen aanwezig zijn, nemen we de locatie van deze objecten in het diagram over. Of vice versa.
Is het mogelijk zonder posities?
Het is mogelijk zonder posities. Maar het zal een beetje verfrommeld zijn; je kunt deze optie in de voorbeelden zien. Dit komt door het feit dat er een algoritme is voor de locatie van knooppunten voor cytoscape , waarbij ook rekening wordt gehouden met de aanwezigheid van groepen. Het specificeren van posities maakt het diagram beter beheersbaar, maar in de fase van de eerste schets van het diagram is het mogelijk zonder posities.
Posities kunnen ook worden gespecificeerd in de Battleship-stijl. Die. het ene knooppunt bevindt zich in a1 en het andere in d5. Het helpt vooral dat cytoscape de objecten op het canvas beweegbaar maakt, d.w.z. we kunnen ze verplaatsen, verschillende lay-outopties bekijken en vervolgens de rangschikking van de elementen die we leuk vinden in de code corrigeren.
Over het algemeen is het begrijpelijk. Je kunt het ook proberen?
Om snel circuits te maken, heb ik natuurlijk een kleine gemaakt , die zelf het schema bijwerkt en de nieuwste versie in de browser opslaat (in localStorage).
Heb je het geprobeerd? Je kunt het nu aan je pagina toevoegen.
Nogmaals:
1. Het script verbinden
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Voeg code toe aan 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. we bewerken de code naar het diagram dat we nodig hebben (ik denk dat het gemakkelijker is dan een uil tekenen :)
Meer details op op github.
Het resultaat?
Ik heb mijn doelen bereikt: het toevoegen van inline-diagrammen aan de documentatie, het formaat is vrij eenvoudig en begrijpelijk. Het is niet geschikt voor supercircuits, maar voor kleine circuits die de structuur van verbindingen verklaren, is het absoluut prima. Je kunt altijd snel iets aanpassen en veranderen in de loop van de tijd. Ja, en collega's kunnen zelf iets in het dok corrigeren, tenminste bijschriften voor objecten, zonder speciale training))
Wat kan er verbeterd worden?
Er zijn hier natuurlijk veel opties. Voeg extra pictogrammen toe (alle bestaande worden inline aan het script toegevoegd). Kies een expressievere set pictogrammen. Maak het mogelijk om de stijl van de verbindingslijn te specificeren. Voeg een achtergrondafbeelding toe.
Wat denk je?
Ik heb al verschillende ideeën voor implementatie in problemen, je kunt de jouwe ook toevoegen in de reacties.
Mijn oplossing is zeker toepasbaar in een beperkt aantal problemen, en misschien zul je een handiger hulpmiddel vinden om diagrammen te tekenen door ze simpelweg te coderen - zoals ze zeggen 'laat me je diagram als code zien'
- (9 soorten grafieken online-editor)
- En als je van supergedetailleerde en complexe diagrammen houdt, dan zul je dit project zeker bewonderen:
Bron: www.habr.com
