V posledných rokoch som sa začal viac venovať dokumentácii. Napísať vysvetľujúci text o fungovaní konkrétneho systému je vo všeobecnosti pomerne jednoduché. Nakreslenie diagramu, ktorý zobrazí všetky kľúčové objekty a prepojenia medzi týmito objektmi, je tiež celkom jednoduché.
Najproblematickejším aspektom je však udržiavanie tejto dokumentácie v aktuálnom stave. A text by bol fajn, ale tie schémy... Pretože... všetka dokumentácia je online, t.j. vo formáte html, potom je text doplnený obrázkami gif/jpeg/png, ktoré v skutočnosti zobrazujú schémy. A diagramy sa kreslia v rôznych programoch, ako je Visio alebo online služby a la draw.io. Potom vyexportujete diagram do grafického formátu a pripojíte ho k html. Je to jednoduché.
Aký je problém?
Schémy sú zvyčajne jednoduché. Presnejšie, nie veľmi komplikované. Áno, počet objektov je tucet alebo dva, počet spojení je približne rovnaký. Plus podpisy, nejaké označenia. Jednoduché schémy možno opísať slovami, ale príliš zložité, ehm... (c) „nebudú rozumieť, pane.“ Schém je veľa, zmeny v nich treba robiť periodicky, epizodicky, t.j. neustále, pretože sledujú vývoj našich produktov.
Môžete vložiť html služby. Skúšali ste to?
Áno samozrejme. Páči sa mi napríklad grafika z gliffy.com. Ak však chcete vykonať zmeny, musíte prejsť do služby tretej strany a upraviť tam. A je ťažšie delegovať opravy na kolegu.
Čo robiť?
Nedávno som v odporúčaniach narazil na úložisko na Githube . Diagram ako kód. Tie. obvod, ktorý potrebujeme, popíšeme v js. Tento js píšeme priamo v tom istom html, kde je iný dokumentačný text.
Mimochodom, dokumentáciu píšem nie úplne v html. Dokumentácia je zvyčajne súbor súborov s textom označenia, ktorý potom nejaký nástroj, napríklad wintersmith, prevedie na plnohodnotnú dokumentačnú stránku. Alebo wiki systém.
Ukázalo sa to veľmi pohodlné: napísali sme text, potom sa otvorí značka skriptu a v nej je popísaný kód JS schémy.
Čo sa zase stalo?
Páčilo sa mi toto úložisko, ale toto nie je jediný príklad, kde je diagram nakreslený pomocou kódu alebo textovej reprezentácie. (Na konci článku budú odkazy na projekty a články, ktoré som zadal do Google v diagrame témy ako kód.)
A nie som jediný, kto upravuje dokumentáciu. Občas prispejú aj kolegovia – opravte slovo, zmeňte popis, vložte nové obrázky.
Preto by som rád videl diagram v čitateľnom, zrozumiteľnom textovom formáte, ktorý by si nevyžadoval dlhé učenie. A na niektorých miestach môžete dokonca jednoducho skopírovať a vložiť, aby ste urýchlili pridávanie nového okruhu.
A ď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 výrazné.
Preto som sa pokúsil predstaviť si diagram ako súbor niekoľkých malých polí, ktoré popisujú uzly, spojenia, skupiny uzlov, ako aj umiestnenie uzlov. Ukázalo sa to, podľa môjho skromného názoru, celkom pohodlné, aj keď, samozrejme, chuť a farba...
Ako je to graf v poli?
- Každý uzol je opísaný identifikátorom, ktorý jedinečne identifikuje uzol.
- Môžete tiež pridať ikonu do uzla a pridať nápis.
- Môžete zadať vzťah medzi dvoma uzlami.
- Pre komunikáciu na diagrame si môžete nastaviť farbu a nápis.
- Smer komunikácie je definovaný ako od zdroja k cieľu. A zdroj a cieľ sú označené identifikátormi uzla.
- Do skupiny je možné pridať jeden alebo viac uzlov.
- Vzťah môže byť špecifikovaný aj zo skupiny, aj do skupiny.
Pomocou týchto jednoduchých pravidiel získame nasledujúci diagram. Len? Celkom.
A je opísaný nasledujúcim kódom js. Hlavná vec je tu objekt prvkov. V ktorých sú označené uzly - uzly, hrany - spojenia.
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, že som neprišiel s nákresom obvodu sám, ale použil som knižnicu je veľmi výkonný vizualizačný nástroj. Vo svojom riešení využívam len zlomok možností.
Dobre, toto je jednoduchý príklad. Môže to byť zložitejšie?
Áno prosím. Na označenie pozícií používame pozície, na označenie skupín označujeme zoznam skupín v skupinách a samotné prvky majú atribút skupiny.
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 takáto schéma takmer pár obrazoviek kódu na notebooku, na druhej strane štruktúra a la json vám umožňuje vyplniť všetky údaje analogicky, rýchlo a môžete ich kopírovať a vkladať.
Prečo sú pozície umiestnené oddelene od uzlov?
Je to pohodlnejšie. Najprv špecifikujeme uzly. Potom môžeme určiť niekoľko skupín a označiť ich v uzloch. Potom označíme spojenia. A až potom, keď sú tam hlavné objekty a spojenia medzi nimi, prevezmeme umiestnenie týchto objektov na diagrame. Alebo naopak.
Dá sa to bez pozícií?
Dá sa to aj bez pozícií. Ale bude to trochu pokrčené, túto možnosť môžete vidieť v príkladoch. Je to spôsobené tým, že existuje algoritmus na umiestnenie uzlov pre cytoscape , ktorá zohľadňuje aj prítomnosť skupín. Zadaním pozícií je diagram lepšie ovládateľný, ale v štádiu prvého návrhu diagramu je to možné aj bez pozícií.
Pozície môžu byť špecifikované aj v štýle Battleship. Tie. jeden uzol sa nachádza v a1 a druhý v d5. Pomáha najmä to, že cytoscape robí objekty na plátne pohyblivými, t.j. môžeme ich presúvať, vidieť rôzne možnosti rozloženia a potom opraviť usporiadanie prvkov, ktoré sa nám v kóde páčia.
Vo všeobecnosti je to pochopiteľné. Môžete tiež vyskúšať?
Samozrejme, aby som si rýchlo vytvoril okruhy, urobil som si malý , ktorý sám aktualizuje schému a ukladá najnovšiu verziu do prehliadača (v localStorage).
Skúšali ste to? Teraz ho môžete pridať na svoju stránku.
Potom znova:
1. Pripojenie skriptu
<script src="https://unpkg.com/@antirek/[email protected]/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 na diagram, ktorý potrebujeme (myslím, že je to jednoduchšie ako nakresliť sovu :)
Viac podrobností na na githube.
Výsledok?
Dosiahol som svoje ciele - pridať do dokumentácie inline diagramy, formát je celkom jednoduchý a zrozumiteľný. Nie je to vhodné pre super obvody, ale pre malé obvody, ktoré vysvetľujú štruktúru spojení, je to úplne v poriadku. Vždy sa dá niečo rýchlo doladiť a časom zmeniť. Áno, a kolegovia môžu sami niečo opraviť v doku, aspoň titulky k objektom, bez špeciálneho školenia))
Čo sa dá zlepšiť?
Možností je tu samozrejme veľa. Pridajte ďalšie ikony (všetky existujúce sa pridajú priamo do skriptu). Zvoľte výraznejšiu sadu ikon. Umožnite špecifikovať štýl spojovacej čiary. Pridajte obrázok na pozadí.
Co si myslis?
Nápadov na implementáciu v číslach už mám niekoľko, do komentárov môžete pridať aj vy.
Moje riešenie je určite použiteľné v úzkom rozsahu problémov a možno nájdete pohodlnejší nástroj na kreslenie diagramov jednoduchým kódovaním - ako sa hovorí „ukážte mi svoj diagram ako kód“
- (9 typov online editora máp)
- A ak máte radi super podrobné a zložité schémy, určite budete tento projekt obdivovať:
Zdroj: hab.com