Az utóbbi pár évben egyre többet foglalkozom a dokumentációval. Megírni egy magyarázó szöveget arról, hogyan működik egy adott rendszer, alapvetően elég egyszerű. Megrajzolni egy ábrát, amelyen az összes kulcsfontosságú objektum és az ezek közötti kapcsolatok szerepelnek, szintén egészen könnyű.
De a legnagyobb probléma az, hogy fenntartsuk ezt a dokumentációt naprakészen. És nem is csak a szöveggel van gond, hanem az ábrákkal is... Mivel az egész dokumentáció online van, vagyis html formátumban, a szöveghez képek tartoznak gif/jpeg/png formátumban, amelyeken maguk az ábrák szerepelnek. Az ábrák különböző programokban, mint például a Visio vagy online szolgáltatásokban, mint a draw.io készülnek. Majd az ábrát exportálod grafikus formátumba, és csatolod a html-hez. Mindez nagyon egyszerű.
Mi a probléma?
Az ábrák általában egyszerűek. Pontosabban, nem túlságosan bonyolultak. Igen, az objektumok száma pár tucat, a kapcsolatoké körülbelül ugyanannyi. Plusz feliratok, valamilyen jelölések. Az egyszerű ábrákat szóban is el lehet mondani, de a túl bonyolultakat, hmm... (c) "nem értik-s". Sok ábra van, folyamatosan változtatni kell rajtuk, mivel ezek követik a termékeink fejlesztését.
Be lehet ágyazni a html szolgáltatásokba. Próbáltad már?
Igen, persze. Például nekem tetszenek a gliffy.com grafikák. De ha változtatni kell, akkor el kell menni egy külső szolgáltatásba, ott kell módosítani. Nehezebb is a kollégának delegálni a módosításokat.
Mit tegyünk?
Nemrég a GitHubon ajánlások között találkoztam egy adattárral . Diagram kód formájában. Azaz, js-ben írjuk le a szükséges ábrát. Ezt a js-t közvetlenül abban a html-ben írjuk, ahol a dokumentáció egyéb szövegei is találhatók.
Megjegyzem, hogy nem teljesen html-ben írom a dokumentációt. Általában a dokumentáció egy fájlgyűjtemény markdown szöveggel, amelyet később egy motor, például wintersmith alakít át egy teljes dokumentációs weboldallá. Vagy wiki-rendszer.
Nagyon kényelmes: itt van a szöveg, majd megnyílik a script tag, és abban le van írva az ábra js kódja.
Mi a baj most?
Ez az adattár tetszett, de ez nem az egyetlen példa arra, amikor az ábrát kód vagy szöveges reprezentáció segítségével rajzolják. (A cikk végén linkek lesznek a diagram as code témájában talált projektekhez és cikkekhez.)
És nem egyedül módosítom a dokumentációt. Néha a kollégák is hozzájárulnak — egy szó javítása, a leírás megváltoztatása, új képek beszúrása.
Ezért szeretnék egy olvasható, érthető szöveges formátumú diagrammot látni, amelyhez nem kellene sokáig tanulni. Egyes helyeken még azt is meg lehetne oldani, hogy egyszerűen másolni és beilleszteni lehet a új séma gyorsabb hozzáadásához.
Egy másik kollégám azt is észrevette, hogy a kód persze jó, de ha struktúrát használnak, akkor minden nagyon szigorú és kifejező lehet.
Ezért próbáltam a sémát úgy elképzelni, mint több kis tömböt, amelyek leírják a csomópontokat, a kapcsolatokat, a csomópontok csoportját, valamint a csomópontok elhelyezkedését. Szerintem ez elég kényelmes lett, bár természetesen ízlés és szín kérdése...
Hogyan néz ki ez a diagram egy tömbben?
- Minden csomópontot egy azonosító ír le, amely egyértelműen meghatározza a csomópontot.
- A csomóponthoz ikont is hozzá lehet adni, valamint feliratot.
- Két csomópont között lehetőség van kapcsolat megadására.
- A kapcsolathoz a sémán meg lehet adni színt, feliratot.
- A kapcsolat iránya úgy van meghatározva, mint forrástól a célig. A forrást és a célt a csomópontok azonosítóival kell megadni.
- Egy vagy több csomópontot csoportba lehet helyezni.
- A kapcsolatot a csoporttól és a csoporthoz is meg lehet adni.
Ezekkel az egyszerű szabályokkal egy ilyen séma jön létre. Egyszerű? Egészen.
A következő js-kóddal van leírva. A fő dolog itt az elements objektum. Amelyben a nodes a csomópontokat, az edges a kapcsolatokat jelöli.
const elements = {
nodes: [ // a csomópontok leírása
{ id: 'client', type: 'smartphone', label: 'Mobilalkalmazás'},
{ id: 'server', type: 'server', label: 'Fő szerver'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [ // a kapcsolatok megadása
{ source: 'client', target: 'server', label: 'kérés' },
{ source: 'server', target: 'db1', label: 'kérés' },
{ source: 'server', target: 'db2', label: 'kérés' },
],
};
Diagram('scheme1', elements);
Természetesen nem én találtam ki a séma megrajzolását, hanem egy könyvtárat használtam. — egy nagyon erős vizualizáló eszköz. Melynek lehetőségeiből csak egy kis részét használom a megoldásomban.
Nyilvánvaló, ez egy egyszerű példa. Lehetséges bonyolultabb?
Igen, kérlek. Az elhelyezkedések megadásához az positions-t, a csoportok meghatározásához a groups listát használjuk, míg maguknak az elemeknek a group attribútumot.
És ez a kód:
<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>
Ez a séma egyrészt - ez szinte pár képernyőnyi kód a laptopon, másrészt a json-stílusú struktúra lehetővé teszi az összes adat gyors feltöltését analógiával, és másolható-beilleszthető.
De miért vannak az positions külön válaszul a csomópontoktól?
Így kényelmesebb. Először megadjuk a node-okat. Ezután megadhatunk pár csoportot, és azokat hozzárendelhetjük a node-okhoz. Majd a kapcsolatok meghatározása következik. Csak ezután, amikor megvannak a fő objektumok és azok közötti kapcsolatok, foglalkozunk azok elhelyezésével a diagramon. Vagy fordítva.
De lehet positions nélkül is?
Positions nélkül is lehetséges. De ez egy kicsit darabos lesz, az ilyen példákat meg lehet nézni. Ez attól függ, hogy a cytoscape-hez van egy nodok elhelyezésére szolgáló algoritmus. , amely a csoportok jelenlétét is figyelembe veszi. A positions megadása segíti a diagram kontrollálását, de az első vázlat készítésekor el lehet hagyni a positions-t.
A positions-t a Haditengerészeti játék stílusában is megadhatjuk. Tehát az egyik node az a1 pozícióban található, a másik pedig a d5-ben. Különösen hasznos, hogy a cytoscape mozgatható objektumokat generál a vásznon, tehát mozgatni tudjuk őket, megnézhetjük a különböző elhelyezési lehetőségeket, és aztán rögzíthetjük a kódba a tetszőleges elhelyezést.
Összességében érthető. Kipróbálhatjuk?
Természetesen, a diagramok gyors létrehozásához készítettem egy kis , amely automatikusan frissíti a diagramot, és a böngészőben tárolja az utolsó verziót (a localStorage-ban).
Megpróbáltátok? Most hozzáadhatjátok a saját oldalatokhoz is.
Akkor még egyszer:
1. Csatlakoztassuk a scriptet
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Add hozzá a html kódhoz
<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. igazítsd a kódot a kívánt diagramhoz (szerintem ez egyszerűbb, mint baglyot rajzolni 🙂
Még részletesebben itt a github-on.
Mi az összefoglaló?
A céljaimat elértem: a diagramok inline beillesztése a dokumentációba, a formátum elég egyszerű és érthető. Nagyobb diagramokhoz nem alkalmas, de kisebb diagramokhoz, amelyek a kapcsolatok struktúráját magyarázzák - nagyon is megfelelő. Mindig gyorsan módosítható és az idő múlásával változtatható. Igen, és a kollégák a dokumentumban saját maguk is szerkeszthetnek valamit, legalább a címkéket az objektumokhoz különösebb oktatás nélkül ))
Mit lehetne javítani?
Itt persze rengeteg lehetőség van. További ikonok hozzáadása (minden meglévő inline van a scriptben). Kifejezőbb ikoncsomag kiválasztása. Képessé tenni a vonalakkal való kapcsolatok stílusának megadására. Háttérkép hozzáadása.
Mit gondoltok erről?
Már van néhány ötletem a megvalósításra az issues között, ti is nyugodtan írjatok a hozzászólásokban.
Az én megoldásom határozottan egy szűk felhasználási területre alkalmazható, és lehet, hogy talál egy kényelmesebb eszközt diagramok rajzolására, egyszerűen kódolva azokat – ahogy mondják: ‘mutasd meg a diagramodat kódként’
- (9 típusú diagram az online szerkesztőhöz)
- És ha Önnek tetszenek a szuper részletes és bonyolult ábrák – akkor ez a projekt bizonyára lenyűgözi Önt:
Forrás: habr.com
