V posledních letech jsem se začal více zabývat dokumentací. Napsat vysvětlující text o tom, jak konkrétní systém funguje, je obecně poměrně jednoduché. Nakreslení diagramu, který zobrazí všechny klíčové objekty a propojení mezi těmito objekty, je také docela snadné.
Nejproblematičtějším aspektem je však udržování této dokumentace v aktuálním stavu. A text by byl fajn, ale ty diagramy... Protože... veškerá dokumentace je online, tzn. ve formátu html, pak je text doplněn obrázky gif/jpeg/png, které ve skutečnosti zobrazují schémata. A diagramy se kreslí v různých programech, jako je Visio nebo online služby a la draw.io. Poté exportujete diagram do grafického formátu a připojíte jej k html. Je to jednoduché.
Jaký je problém?
Schémata jsou obvykle jednoduchá. Přesněji nepříliš složitě. Ano, počet objektů je tucet nebo dva, počet spojení je přibližně stejný. Plus podpisy, nějaká označení. Jednoduchá schémata lze popsat slovy, ale příliš složitá, ehm... (c) "nebudou rozumět, pane." Schémat je mnoho, je potřeba v nich provádět změny periodicky, epizodicky, tzn. neustále, protože sledují vývoj našich produktů.
Můžete vložit html služby. Zkusil jsi to?
Ano jistě. Líbí se mi například grafika z gliffy.com. Chcete-li však provést změny, musíte přejít do služby třetí strany a upravit tam. A je obtížnější delegovat opravy na kolegu.
Co dělat?
Nedávno jsem v doporučeních narazil na repozitář na Githubu . Diagram jako kód. Tito. obvod, který potřebujeme, popíšeme v js. Tento js píšeme přímo ve stejném html, kde je další dokumentační text.
Mimochodem, píšu dokumentaci ne úplně v html. Dokumentace je obvykle sada souborů s markdown textem, který je pak převeden na plnohodnotný dokumentační web pomocí nějakého nástroje, například wintersmith. Nebo wiki systém.
Ukázalo se to velmi pohodlné: napsali jsme text, pak se otevře značka skriptu a v ní je popsán kód JS schématu.
co se zase stalo?
Toto úložiště se mi líbilo, ale není to jediný příklad, kde je diagram nakreslen pomocí kódu nebo textové reprezentace. (Na konci článku budou odkazy na projekty a články, které jsem zadal do Googlu v diagramu tématu jako kód.)
A nejsem jediný, kdo upravuje dokumentaci. Někdy přispívají i kolegové – opravte slovo, změňte popis, vložte nové obrázky.
Proto bych rád viděl diagram v čitelném, srozumitelném textovém formátu, který by nevyžadoval dlouhé učení. A na některých místech můžete dokonce jednoduše zkopírovat a vložit, abyste urychlili přidání nového obvodu.
A další kolega poznamenal, že kód je samozřejmě dobrý, ale pokud použijete strukturu, vše může být velmi striktní a výrazné.
Proto jsem se pokusil představit si diagram jako sadu několika malých polí, která popisují uzly, spojení, skupiny uzlů a také umístění uzlů. Ukázalo se to podle mého skromného názoru docela příhodné, i když samozřejmě ta chuť a barva...
Jak je to graf v poli?
- Každý uzel je popsán identifikátorem, který uzel jednoznačně identifikuje.
- Můžete také přidat ikonu do uzlu a přidat nápis.
- Můžete určit vztah mezi dvěma uzly.
- Pro komunikaci na diagramu lze nastavit barvu a nápis.
- Směr komunikace je definován jako od zdroje k cíli. A zdroj a cíl jsou označeny identifikátory uzlů.
- Do skupiny lze přidat jeden nebo více uzlů.
- Vztah lze také specifikovat jak ze skupiny, tak do skupiny.
Pomocí těchto jednoduchých pravidel získáme následující schéma. Prostě? Docela.
A je popsán následujícím kódem js. Hlavní věc je zde objekt prvků. Ve kterých jsou uvedeny uzly - uzly, hrany - spoje.
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);
Samozřejmě jsem nepřišel s nákresem obvodu sám, ale použil jsem knihovnu je velmi výkonný vizualizační nástroj. Ve svém řešení využívám jen zlomek možností.
Dobře, toto je jednoduchý příklad. Může to být složitější?
Ano prosím. K označení pozic používáme pozice, k označení skupin označujeme seznam skupin ve skupinách a samotné prvky mají atribut 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 jedné straně je takové schéma téměř několik obrazovek kódu na notebooku, na druhé straně struktura a la json vám umožňuje analogicky, rychle vyplnit všechna data a můžete je kopírovat a vkládat.
Proč jsou pozice umístěny odděleně od uzlů?
Je to pohodlnější. Nejprve určíme uzly. Poté můžeme určit několik skupin a označit je v uzlech. Poté označíme spoje. A teprve potom, když jsou tam hlavní objekty a spojení mezi nimi, převezmeme umístění těchto objektů na diagramu. Nebo naopak.
Jde to bez pozic?
Jde to i bez pozic. Bude se ale trochu mačkat, tuto možnost můžete vidět na příkladech. To je způsobeno skutečností, že existuje algoritmus pro umístění uzlů pro cytoscape , která zohledňuje i přítomnost skupin. Zadáním pozic je diagram lépe ovladatelný, ale ve fázi prvního návrhu diagramu je možné bez pozic.
Pozice mohou být také specifikovány ve stylu Battleship. Tito. jeden uzel se nachází v a1 a druhý v d5. Pomáhá zejména to, že cytoscape činí objekty na plátně pohyblivými, tzn. můžeme je přesouvat, vidět různé možnosti rozvržení a pak opravit uspořádání prvků, které se nám v kódu líbí.
Obecně je to pochopitelné. Můžete také zkusit?
Samozřejmě, abych si rychle vytvořil obvody, udělal jsem si malý , který sám aktualizuje schéma a ukládá nejnovější verzi do prohlížeče (v localStorage).
Zkusil jsi to? Nyní jej můžete přidat na svou stránku.
Pak znovu:
1. Připojení skriptu
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Přidejte 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, který potřebujeme (myslím, že je to jednodušší než nakreslit sovu :)
Více podrobností na na githubu.
Výsledek?
Svého cíle jsem dosáhl – přidat do dokumentace inline diagramy, formát je celkem jednoduchý a srozumitelný. Není to vhodné pro super obvody, ale pro malé obvody, které vysvětlují strukturu spojení, je to naprosto v pořádku. Vždy můžete rychle něco vyladit a změnit v průběhu času. Ano, a kolegové mohou sami něco opravit v doku, alespoň titulky k objektům, bez speciálního školení))
Co lze zlepšit?
Možností je zde samozřejmě spousta. Přidejte další ikony (všechny existující jsou přidány přímo do skriptu). Zvolte výraznější sadu ikon. Umožněte specifikovat styl spojovací čáry. Přidejte obrázek na pozadí.
Co myslíš?
Mám již několik nápadů na implementaci do vydání, můžete také přidat svůj do komentářů.
Moje řešení je určitě použitelné v úzkém okruhu problémů a možná najdete pohodlnější nástroj pro kreslení diagramů tím, že je jednoduše nakódujete - jak se říká 'ukaž mi svůj diagram jako kód'
- (9 typů online editoru grafů)
- A pokud máte rádi super podrobné a složité diagramy, pak tento projekt určitě obdivujete:
Zdroj: www.habr.com