V posledních pár letech jsem se více věnoval dokumentaci. Napsat vysvětlující text o tom, jak funguje nějaký systém, je celkem jednoduché. Nakreslit diagram, na kterém budou zobrazeny všechny klíčové objekty, vztahy mezi těmito objekty, také není těžké.
Ale nejproblematičtější částí je udržovat tuto dokumentaci aktuální. A to nejen text, ale i diagramy… Vzhledem k tomu, že veškerá dokumentace je online, tedy ve formátu HTML, jsou k textu přiloženy obrázky gif/jpeg/png, na kterých jsou vlastně zobrazeny diagramy. A diagramy se kreslí v různých programech, jako je Visio nebo online službách jako např. draw.io. Poté exportujete diagram do grafického formátu a přiložíte ho k HTML. To je jednoduché.
V čem je problém?
Diagramy jsou obvykle jednoduché. Přesněji, nejsou příliš složité. Ano, počet objektů je asi deset či dva, počet vztahů zhruba stejný. K tomu popisky, nějaké označení. Jednoduché diagramy lze popsat také slovy, ale příliš složité, ehm… (c) „nepochopí“. Je jich mnoho, změny v nich je třeba provádět periodicky, tedy neustále, protože následují vývoj našich produktů.
Můžete přece integrovat službu HTML. Zkoušel jste to?
Ano, samozřejmě. Mně se například líbí grafy na gliffy.com. Ale pro úpravy musíte jít na externí službu a tam je opravit. A je těžší delegovat provedení změn kolegovi.
Co dělat?
Nedávno mi na GitHubu přišel do doporučení repozitář . Diagram jako kód. Tedy popisujeme v JS potřebný diagram. Tento JS píšeme přímo v tom HTML, kde je také ostatní text dokumentace.
Mimochodem, já píšu dokumentaci ne úplně v HTML. Obvykle dokumentace je soubor s markdown textem, který se pak převádí na plnohodnotný web dokumentace nějakým engine, například wintersmith. Nebo wiki systém.
To je velmi pohodlné: tedy jsme napsali text, pak se otevře tag script a v něm je popsán JS kód diagramu.
Co je teď zase špatně?
Tento repozitář se mi líbil, ale to není jediný příklad, kdy se diagram kreslí pomocí kódu nebo textové reprezentace. (Na konci článku budou odkazy na projekty a články, které jsem našel na téma diagram jako kód.)
A já rozhodně nejsem sám, kdo upravuje dokumentaci. Někdy se na tom podílejí i kolegové — oprava slov, změna popisu, přidání nových obrázků.
Rád bych viděl diagram v čitelném a srozumitelném textovém formátu, kterému by se člověk nemusel dlouho učit. A někdy je možné prostě použít copy-paste pro urychlení přidání nové schémy.
A další kolega si všiml, že kód je samozřejmě dobrý, ale pokud použijeme strukturu, může být vše velmi přísné a výstižné.
Proto jsem se pokusil představit si schéma jako soubor několika malých polí, která popisují uzly, vazby, skupiny uzlů a také umístění uzlů. Z mého skromného pohledu to vypadá dost pohodlně, i když, jak se říká, na chutích…
Jak to schéma v poli vypadá?
- Každý uzel je popsán identifikátorem, který jednoznačně určuje uzel.
- K uzlu lze také přidat ikonu a popis.
- Mezi dvěma uzly lze určit vazbu.
- Pro vazbu v schématu lze nastavit barvu a popis.
- Směr vazby je definován jako od zdroje k cíli. A zdroj i cíl jsou určeny identifikátory uzlu.
- Jednoho nebo více uzlů lze přidat do skupiny.
- Vazbu lze také určit od skupiny a k skupině.
Použitím těchto jednoduchých pravidel dostaneme takové schéma. Jednoduché? Docela určitě.
A popisuje se to následujícím js-kódem. Hlavní zde je objekt elements. Kde jsou uvedeny nodes — uzly, edges — vazby.
const elements = {
nodes: [ // popisujeme uzly
{ id: 'client', type: 'smartphone', label: 'Mobilní aplikace'},
{ id: 'server', type: 'server', label: 'Hlavní server'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [ // určujeme vazby
{ source: 'client', target: 'server', label: 'požadavek' },
{ source: 'server', target: 'db1', label: 'požadavek' },
{ source: 'server', target: 'db2', label: 'požadavek' },
],
};
Diagram('scheme1', elements);
Samozřejmě, že nakreslení schématu jsem nevymyslel sám, ale využil jsem knihovnu. — velmi mocný vizualizační nástroj. Z jeho možností v mém řešení využívám pouze část.
Jasně, to je jednoduchý příklad. Můžeme to udělat složitější?
Ano, samozřejmě. Pro určení pozic používáme positions, pro určení skupin uvádíme seznam skupin v groups, a pro samotné prvky atribut group.
A tohle 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>
Tento schéma je z jedné strany téměř párem obrazovek kódu na notebooku, z druhé strany struktura ve stylu JSON umožňuje rychle vyplnit všechna data formou analogie, snadno a pomocí copy-paste.
A proč jsou pozice uvedeny odděleně od uzlů?
Je to pohodlnější. Nejprve uvádíme uzly. Poté můžeme uvést pár skupin a zapracovat je do uzlů. Pak určíme vazby. A až poté, když máme základní objekty a vazby mezi nimi, se zabýváme umístěním těchto objektů v schématu. Nebo naopak.
Můžeme to udělat i bez pozic?
Ano, jde to i bez pozic. Ale bude to trochu zhuštěné, takový příklad si můžete prohlédnout. Je to způsobeno tím, že pro Cytoscape existuje algoritmus pro umístění uzlů. , který také zohledňuje přítomnost skupin. Uvedení pozic činí schéma více kontrolovatelným, ale ve fázi prvního náčrtku schématu to lze obejít i bez pozic.
Pozice lze také uvádět ve stylu lodního boje. Tedy jeden uzel se umístí do a1, a druhý do d5. Zvláště pomáhá, že Cytoscape vytváří objekty na plátně pohyblivé, tzn. můžeme je posunout, podívat se na různé varianty uspořádání, a poté zakódovat oblíbené umístění prvků.
Celkově je to jasné. Můžeme to vyzkoušet?
Samozřejmě, pro rychlé vytváření schémat jsem si udělal malý , který sám aktualizuje schéma a v prohlížeči uchovává poslední verzi (v localStorage).
Zkusili jste? Teď to lze přidat i na svoji stránku.
Takže ještě jednou:
1. Připojíme skript
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Přidáme do HTML kódu
<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. opravíme kód do požadovaného schématu (myslím, že je to jednodušší než nakreslit sovu 🙂
Podrobněji na na GitHubu.
Jaký je výsledek?
Svých cílů jsem dosáhl – udělat přidání schémat inline do dokumentace, formát je dost jednoduchý a srozumitelný. Pro super schémata to nebude fungovat, ale pro malé schémata, která objasňují strukturu vazeb – velmi dobré. Vždy lze rychle upravit a něco v průběhu času změnit. A kolegové mohou v dokumentaci také něco opravit, alespoň popisy k objektům bez zvláštního školení))
Co lze zlepšit?
Zde je samozřejmě řada možností. Přidat další ikony (všechny dostupné jsou přidány inline ve skriptu). Vybrat expresivnější soubor ikon. Umožnit nastavení stylu linií vazeb. Přidat pozadí obrázkem.
A co si myslíte vy?
Mám už několik nápadů na realizaci v issues, přidejte také své do komentářů.
Moje řešení je určitě použitelné v úzkém spektru úkolů, a možná najdete pohodlnější nástroj na kreslení diagramů, jednoduše je naprogramováním — jak se říká 'ukázat mi svůj diagram jako kód'
- (9 typů diagramů online editor)
- A pokud máte rádi super detailní a složité schémata — určitě vás tento projekt osloví:
Zdroj: habr.com
