Az elmúlt néhány évben egyre jobban foglalkoztam a dokumentációval. Egy magyarázó szöveget írni ennek vagy annak a rendszernek a működéséről általában meglehetősen egyszerű. Az összes kulcsfontosságú objektumot és az objektumok közötti kapcsolatokat megjelenítő diagram megrajzolása szintén meglehetősen egyszerű.
De a legproblémásabb szempont a dokumentáció naprakészen tartása. És a szöveg jó lenne, de a diagramok... Mert... minden dokumentáció online, pl. html formátumban, akkor a szöveghez gif/jpeg/png képek társulnak, amelyeken tulajdonképpen a diagramok láthatók. A diagramokat pedig különféle programokban rajzolják meg, mint például a Visio vagy a la draw.io online szolgáltatások. Ezután exportálja a diagramot grafikus formátumba, és csatolja a html-hez. Ez egyszerű.
Mi a probléma?
A sémák általában egyszerűek. Pontosabban nem túl bonyolult. Igen, az objektumok száma egy-két tucat, a kapcsolatok száma megközelítőleg ugyanannyi. Plusz aláírások, néhány megnevezés. Az egyszerű sémákat le lehet írni szavakkal, de a túl bonyolultakat, hm... (c) „nem fogják érteni, uram”. Sok séma létezik, ezeken időszakosan, epizodikusan kell változtatni, pl. folyamatosan, mert követik termékeink fejlődését.
Beágyazhatja a szolgáltatás html-jét. Kibróbáltad?
Igen, persze. Például szeretem a gliffy.com grafikáját. A módosítások végrehajtásához azonban fel kell lépnie egy harmadik féltől származó szolgáltatásra, és ott kell szerkesztenie. És nehezebb átruházni a javításokat egy kollégára.
Mit kell tenni?
Nemrég találkoztam egy adattárral a Githubon az ajánlásokban . Diagram mint kód. Azok. js-ben írjuk le a szükséges áramkört. Ezt a js-t közvetlenül ugyanabba a html-be írjuk, ahol a többi dokumentáció szövege található.
A dokumentációt egyébként nem teljesen html-ben írom. A dokumentáció jellemzően egy fájlok halmaza leértékelési szöveggel, amelyet aztán valamilyen motor, például a wintersmith teljes értékű dokumentációs oldallá alakít. Vagy egy wiki rendszer.
Nagyon kényelmesnek bizonyul: megírtuk a szöveget, majd megnyílik a script tag, és le van írva benne a séma JS kódja.
Mi a baj már megint?
Tetszett ez a tárhely, de nem ez az egyetlen példa, ahol egy diagramot kóddal vagy szöveges ábrázolással rajzolnak. (A cikk végén linkek lesznek azokhoz a projektekhez és cikkekhez, amelyeket a témadiagramon kódként Google-be kerestem.)
És nem én vagyok az egyetlen, aki szerkeszti a dokumentációt. Néha a kollégák is hozzájárulnak - javítsanak ki egy szót, módosítsanak egy leírást, szúrjanak be új képeket.
Ezért szeretném a diagramot olvasható, érthető szöveges formátumban látni, amely nem igényel hosszú tanulási görbét. Néhány helyen pedig egyszerűen másolhat és beilleszthet, hogy felgyorsítsa az új áramkör hozzáadását.
Egy másik kolléga pedig megjegyezte, hogy a kód természetesen jó, de ha struktúrát használunk, minden nagyon szigorú és kifejező lehet.
Ezért a diagramot több kis tömb halmazaként próbáltam elképzelni, amelyek csomópontokat, kapcsolatokat, csomópontcsoportokat, valamint a csomópontok elhelyezkedését írják le. Szerény véleményem szerint egész kényelmesnek bizonyult, bár persze az íze és a színe...
Milyen ez a diagram egy tömbben?
- Minden csomópontot egy azonosító ír le, amely egyedileg azonosítja a csomópontot.
- A csomóponthoz ikont is hozzáadhat, és feliratot is hozzáadhat.
- Megadhat kapcsolatot két csomópont között.
- A diagramon történő kommunikációhoz beállíthatja a színt és a feliratot.
- A kommunikáció irányát a forrástól a célig definiálják. A forrást és a célt pedig csomópontazonosítók jelzik.
- Egy vagy több csomópont hozzáadható egy csoporthoz.
- A kapcsolat csoportról és csoportról is megadható.
Ezeket az egyszerű szabályokat alkalmazva a következő diagramot kapjuk. Éppen? Egészen.
És ezt a következő js kód írja le. A fő dolog itt az elemek objektum. Amelyekben csomópontok vannak feltüntetve - csomópontok, élek - kapcsolatok.
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);
Természetesen nem magam találtam ki az áramkör rajzát, hanem a könyvtárat használtam egy nagyon hatékony vizualizációs eszköz. A megoldásomban a lehetőségeknek csak a töredékét használom ki.
Oké, ez egy egyszerű példa. Lehet ennél bonyolultabb?
Igen, kérem. A pozíciók jelzésére pozíciókat használunk, a csoportok jelzésére a csoportok listáját jelöljük meg, maguknak az elemeknek pedig csoport attribútuma van.
É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>
Egy ilyen séma egyrészt szinte pár képernyőnyi kód egy laptopon, másrészt az a la json szerkezet lehetővé teszi, hogy analógia útján gyorsan kitöltsd az összes adatot, és másolható-beilleszthető.
Miért helyezik el a pozíciókat a csomópontoktól külön?
Kényelmesebb. Először a csomópontokat határozzuk meg. Ezután megadhatunk pár csoportot, és ezeket csomópontokban jelezhetjük. Ezután kijelöljük a kapcsolatokat. És csak akkor, amikor a fő objektumok és a köztük lévő kapcsolatok megvannak, vesszük fel ezeknek az objektumoknak a helyét a diagramon. Vagy fordítva.
Lehetséges pozíciók nélkül?
Pozíciók nélkül is lehetséges. De egy kicsit gyűrött lesz; ezt a lehetőséget láthatja a példákban. Ez annak a ténynek köszönhető, hogy létezik egy algoritmus a cytoscape csomópontjainak elhelyezkedésére , amely a csoportok jelenlétét is figyelembe veszi. A pozíciók megadásával a diagram ellenőrizhetőbbé válik, de a diagram első vázlatának szakaszában lehetséges pozíciók nélkül is.
A pozíciók Battleship stílusban is megadhatók. Azok. az egyik csomópont az a1-ben, a másik a d5-ben található. Különösen segít, hogy a cytoscape mozgathatóvá teszi a vásznon lévő tárgyakat, pl. mozgathatjuk őket, láthatjuk a különböző elrendezési lehetőségeket, majd javíthatjuk a kódban a nekünk tetsző elemek elrendezését.
Általában véve érthető. Te is kipróbálhatod?
Természetesen, hogy gyorsan létrehozzam az áramköröket, készítettem magamnak egy kicsi , amely maga frissíti a sémát, és a legfrissebb verziót tárolja a böngészőben (a localStorage-ban).
Kibróbáltad? Most hozzáadhatja az oldalához.
Aztán megint:
1. A szkript összekapcsolása
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Kód hozzáadása a html-hez
<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. szerkesztjük a kódot a szükséges diagramra (szerintem egyszerűbb, mint baglyot rajzolni :)
További részletek a címen a githubon.
Az eredmény?
Elértem a kitűzött céljaimat - hogy a dokumentációt soron belüli diagramokkal egészítsem ki, a formátum meglehetősen egyszerű és érthető. Szuperáramkörökhöz nem alkalmas, de kis áramkörökhöz, amelyek megmagyarázzák a kapcsolatok szerkezetét, teljesen rendben van. Idővel bármikor gyorsan módosíthat és megváltoztathat valamit. Igen, és a kollégák maguk is javíthatnak valamit a dokkban, legalább a tárgyak feliratait, speciális képzés nélkül))
Mit lehet javítani?
Természetesen itt is rengeteg lehetőség van. Adjon hozzá további ikonokat (az összes létező bekerül a szkriptbe). Válasszon kifejezőbb ikonkészletet. Lehetővé teszi a csatlakozási vonal stílusának megadását. Adjon hozzá egy háttérképet.
Mit gondolsz?
Számos megvalósítási ötletem van már számokban, kommentben megírhatod a sajátodat is.
Megoldásom határozottan alkalmazható egy szűk problémakörben, és talán talál egy kényelmesebb eszközt diagramok rajzolásához, ha egyszerűen kódolja őket - ahogy mondják "mutasd meg a diagramodat kódként"
- (9 féle diagram online szerkesztő)
- És ha szereted a szuper részletes és összetett diagramokat, akkor biztosan megcsodálod ezt a projektet:
Forrás: will.com