V posledných rokoch som sa viac zaoberal dokumentáciou. Napísať vysvetľujúci text o tom, ako konkrétny systém funguje, je vo všeobecnosti celkom jednoduché. Nakreslenie diagramu zobrazujúceho všetky kľúčové objekty a vzťahy medzi nimi je tiež celkom jednoduché.
Najväčšou výzvou je však udržiavať túto dokumentáciu aktuálnu. Text by bol v poriadku, ale diagramy... Keďže všetka dokumentácia je online vo formáte HTML, text je sprevádzaný obrázkami gif/jpeg/png, ktoré diagramy skutočne zobrazujú. Diagramy sa kreslia v rôznych programoch, ako je Visio, alebo v online službách, ako je draw.io. Potom diagram exportujete do grafického formátu a pripojíte ho k HTML. Je to také jednoduché.
Aký je problém?
Diagramy sú zvyčajne jednoduché. Presnejšie povedané, nie príliš zložité. Áno, je tam tucet alebo dva objekty a približne rovnaký počet spojení. Plus popisky a nejaké poznámky. Jednoduché diagramy sa dajú opísať slovne, ale príliš zložité, ehm... (c) „nebudú pochopené“. Existuje veľa diagramov a zmeny v nich je potrebné robiť pravidelne, epizodicky, t. j. neustále, pretože sledujú vývoj našich produktov.
Môžete vložiť HTML kód služby. Skúšali ste to?
Áno, samozrejme. Napríklad sa mi páčia grafy na gliffy.com. Ale ak chcete vykonať zmeny, musíte ísť do služby tretej strany a upraviť ich tam. A je ťažšie delegovať úpravu na kolegu.
Čo robiť?
Nedávno som narazil na repozitár v odporúčaniach GitHubu Diagram ako kód. To znamená, že diagram, ktorý potrebujeme, popíšeme v JavaScripte. Tento JavaScript píšeme priamo v rovnakom HTML ako zvyšok dokumentácie.
Mimochodom, nepíšem dokumentáciu výlučne v HTML. Dokumentácia je zvyčajne sada súborov Markdown, ktoré sa potom pomocou nejakého nástroja, ako napríklad Wintersmith, alebo wiki systému prevedú na plnohodnotnú dokumentačnú stránku.
Ukazuje sa to veľmi pohodlné: tu sme napísali text, potom sa otvorí tag skriptu a v ňom je popísaný JS kód schémy.
Čo sa zasa deje?
Tento repozitár sa mi páčil, ale nie je to jediný príklad diagramu vykresleného pomocou kódu alebo textovej reprezentácie. (Na konci článku sú odkazy na projekty a články, ktoré som našiel na Googli o diagrame ako kóde.)
A nie som jediný, kto upravuje dokumentáciu. Niekedy prispievajú aj moji kolegovia – opravujú slovo, menia popis, vkladajú nové obrázky.
Preto by som rád videl diagram v čitateľnom a zrozumiteľnom textovom formáte, ktorý by si nevyžadoval veľa učenia. Na niektorých miestach by som ho dokonca rád jednoducho skopíroval a vložil, aby sa urýchlilo pridávanie nových diagramov.
Ďalší kolega poznamenal, že kód je, samozrejme, dobrý, ale ak použijete štruktúru, všetko môže byť veľmi prísne a expresívne.
Takže som sa pokúsil reprezentovať diagram ako súbor niekoľkých malých polí, ktoré opisujú uzly, pripojenia, skupiny uzlov a umiestnenia uzlov. Podľa môjho skromného názoru sa to ukázalo ako celkom pohodlné, hoci, samozrejme, na vkus sa nehľadí...
Ako je toto diagram v poli?
- Každý uzol je opísaný identifikátorom, ktorý ho jednoznačne identifikuje.
- K uzlu môžete pridať aj ikonu a popis.
- Vzťah je možné špecifikovať medzi dvoma uzlami.
- Pre pripojenie na diagrame môžete nastaviť farbu a popis.
- Smer komunikácie je definovaný ako od zdroja k cieľu a zdroj a cieľ sú určené identifikátormi uzlov.
- Do skupiny je možné pridať jeden alebo viac uzlov.
- Pripojenie je možné zadať aj zo skupiny aj do skupiny.
Pomocou týchto jednoduchých pravidiel dostaneme túto schému. Jednoduchá? Celkom.
Je to popísané nasledujúcim kódom JavaScript. Kľúčom je tu objekt elements, ktorý špecifikuje uzly a hrany.
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);
Samozrejme, s nákresom obvodu som neprišiel sám, ale použil som knižnicu — veľmi výkonný vizualizačný nástroj, z ktorého vo svojom riešení používam len zlomok.
Dobre, to je jednoduchý príklad. Vieš to zložitejšie vysvetliť?
Áno, prosím. Na určenie pozícií používame atribút positions; na určenie skupín určujeme zoznam skupín v skupinách; a samotné prvky používajú atribút group.
A toto je 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>
Na jednej strane je táto schéma takmer ako pár obrazoviek kódu na notebooku, na druhej strane štruktúra podobná JSON umožňuje podobným spôsobom, rýchlo a pomocou kopírovania a vkladania vyplniť všetky údaje.
Prečo sú pozície oddelené od uzlov?
Je to takto pohodlnejšie. Najprv určíme uzly. Potom môžeme určiť niekoľko skupín a označiť ich ako uzly. Potom definujeme prepojenia. Až potom, keď sú hlavné objekty a prepojenia medzi nimi nadviazané, začneme tieto objekty usporiadať na diagrame. Alebo naopak.
Je to možné aj bez pozícií?
Môžete to urobiť aj bez pozícií. Ale bude to trochu komplikované; túto možnosť môžete vidieť v príkladoch. Je to preto, že Cytoscape má algoritmus na umiestnenie uzlov. , ktorý zohľadňuje aj prítomnosť skupín. Zadanie pozícií umožňuje lepšiu kontrolu nad diagramom, ale v počiatočnej fáze návrhu diagramu je možné sa zaobísť bez pozícií.
Pozície je možné zadať aj v štýle bojovej lode. To znamená, že jeden uzol je umiestnený na a1 a druhý na d5. Schopnosť Cytoscape vytvárať pohyblivé objekty na plátne je obzvlášť užitočná, čo znamená, že ich môžeme presúvať, skúmať rôzne možnosti rozloženia a potom v kóde uzamknúť požadované usporiadanie prvkov.
Celkovo chápem. Môžem to skúsiť?
Samozrejme, aby som rýchlo vytvoril obvody, vyrobil som si jeden malý , ktorý aktualizuje samotnú schému a ukladá najnovšiu verziu do prehliadača (v localStorage).
Vyskúšali ste to? Teraz si to môžete pridať na svoju stránku.
Potom ešte raz:
1. Pripojenie skriptu
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Pridajte kód do 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. Upravíme kód, aby sme získali potrebný diagram (myslím, že je to jednoduchšie ako kresliť sovu :)
Viac podrobností o na GitHube.
Výsledok?
Dosiahol som svoje ciele – povoliť v dokumentácii vkladanie diagramov. Formát je pomerne jednoduchý a priamočiary. Nie je vhodný pre superdiagramy, ale pre malé diagramy vysvetľujúce štruktúru prepojení je celkom dobrý. Vždy ho môžete rýchlo upraviť a časom niečo zmeniť. A kolegovia si tiež môžu sami upravovať dokumentáciu, aspoň popisy objektov, bez väčšieho školenia.
Čo sa dá zlepšiť?
Samozrejme, existuje tu množstvo možností. Pridajte ďalšie ikony (všetky existujúce sa pridajú priamo do skriptu). Vyberte výraznejšiu sadu ikon. Povoľte možnosť určiť štýl čiary odkazu. Pridajte obrázok na pozadí.
Čo si o tom myslíš?
Už mám niekoľko nápadov na implementáciu v problémoch, môžete tiež pridať tie svoje do komentárov.
Moje riešenie je určite použiteľné pre úzky okruh úloh a možno nájdete pohodlnejší nástroj na kreslenie diagramov jednoduchým ich kódovaním – ako sa hovorí, „ukážte mi svoj diagram ako kód“.
- (9 typov grafov online editor)
- A ak milujete super detailné a komplexné návrhy, tento projekt si určite zamilujete:
Zdroj: hab.com
