V zadnjih nekaj letih sem se začel bolj ukvarjati z dokumentacijo. Pisanje obrazložitvenega besedila o delovanju določenega sistema je na splošno precej preprosto. Tudi risanje diagrama, ki bo prikazal vse ključne objekte in povezave med temi objekti, je precej enostavno.
Toda najbolj problematičen vidik je posodabljanje te dokumentacije. In besedilo bi bilo v redu, ampak diagrami... Ker... vsa dokumentacija je na spletu, tj. v formatu html, potem besedilo spremljajo slike gif/jpeg/png, ki dejansko prikazujejo diagrame. In diagrami so narisani v različnih programih, kot je Visio ali spletnih storitvah a la draw.io. Nato izvozite diagram v grafični format in ga priložite v html. Enostavno je.
Kaj je problem?
Sheme so običajno preproste. Natančneje, ni zelo zapleteno. Da, število objektov je ducat ali dva, število povezav je približno enako. Plus podpisi, nekaj oznak. Enostavne sheme je mogoče opisati z besedami, preveč zapletene pa, ah... (c) "ne bodo razumeli, gospod." Shem je veliko, spreminjati jih je treba občasno, epizodično, tj. nenehno, saj sledijo razvoju naših izdelkov.
Vdelate lahko html storitve. Ste poskusili?
Ja seveda. Na primer, všeč mi je grafika z gliffy.com. Če pa želite narediti spremembe, morate iti v storitev tretje osebe in tam urediti. In težje je prenesti popravke na kolega.
Kaj storiti?
Pred kratkim sem med priporočili naletel na repozitorij na Githubu . Diagram kot koda. Tisti. opišemo vezje, ki ga potrebujemo v js. Ta js zapišemo neposredno v isti html, kjer je drugo besedilo dokumentacije.
Mimogrede, dokumentacijo pišem ne povsem v html. Običajno je dokumentacija nabor datotek z označenim besedilom, ki ga nato nek mehanizem, na primer wintersmith, pretvori v popolno mesto dokumentacije. Ali wiki sistem.
Izkazalo se je zelo priročno: napisali smo besedilo, nato se odpre oznaka skripta in v njej je opisana koda JS sheme.
Kaj je spet narobe?
To skladišče mi je bilo všeč, vendar to ni edini primer, kjer je diagram narisan s kodo ali besedilno predstavitvijo. (Na koncu članka bodo povezave do projektov in člankov, ki sem jih Googlal na diagramu teme kot kodo.)
In nisem edini, ki ureja dokumentacijo. Včasih kaj prispevajo tudi sodelavci – popravijo besedo, spremenijo opis, vstavijo nove slike.
Zato bi rad videl diagram v berljivi in razumljivi besedilni obliki, ki ne bi zahtevala dolge krivulje učenja. Na nekaterih mestih lahko celo preprosto kopirate in prilepite, da pospešite dodajanje novega vezja.
In drugi kolega je opozoril, da je koda seveda dobra, a če uporabljate strukturo, je lahko vse zelo strogo in ekspresivno.
Zato sem si poskušal diagram predstavljati kot niz več majhnih nizov, ki opisujejo vozlišča, povezave, skupine vozlišč, pa tudi lokacijo vozlišč. Izkazalo se je, po mojem skromnem mnenju, precej priročno, čeprav sta seveda okus in barva ...
Kako je to grafikon v nizu?
- Vsako vozlišče je opisano z identifikatorjem, ki enolično identificira vozlišče.
- Vozlišču lahko dodate tudi ikono in dodate napis.
- Določite lahko razmerje med dvema vozliščema.
- Za komunikacijo na diagramu lahko nastavite barvo in napis.
- Smer komunikacije je opredeljena kot od vira do cilja. In vir in cilj sta označena z identifikatorji vozlišč.
- V skupino je mogoče dodati eno ali več vozlišč.
- Razmerje je mogoče določiti tudi od skupine in do skupine.
Z uporabo teh preprostih pravil dobimo naslednji diagram. Samo? Čisto.
Opisuje ga naslednja koda js. Glavna stvar tukaj je predmet elementov. V katerih so označena vozlišča - vozlišča, robovi - povezave.
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);
Seveda se risbe vezja nisem domislil sam, ampak sem uporabil knjižnico je zelo močno orodje za vizualizacijo. V svoji rešitvi uporabljam le delček možnosti.
V redu, to je preprost primer. Ali je lahko bolj zapleteno?
Da, prosim. Za označevanje pozicij uporabljamo položaje, za označevanje skupin označujemo seznam skupin v skupinah, sami elementi pa imajo atribut skupine.
In to je koda:
<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>
Po eni strani je takšna shema skoraj nekaj zaslonov kode na prenosnem računalniku, po drugi strani pa struktura a la json omogoča, da vse podatke izpolnite po analogiji, hitro in lahko kopirate-prilepite.
Zakaj so pozicije postavljene ločeno od vozlišč?
Je bolj udobno. Najprej določimo vozlišča. Nato lahko določimo nekaj skupin in jih označimo v vozliščih. Nato označimo povezave. In šele takrat, ko so glavni predmeti in povezave med njimi, prevzamemo lokacijo teh predmetov na diagramu. Ali obratno.
Je mogoče brez položajev?
Možno je brez položajev. Vendar bo malo zmečkano, to možnost lahko vidite v primerih. To je posledica dejstva, da obstaja algoritem za lokacijo vozlišč za cytoscape , ki upošteva tudi prisotnost skupin. Če določite položaje, je diagram bolj nadzorovan, vendar je na stopnji prvega osnutka diagrama mogoče brez položajev.
Položaje je mogoče določiti tudi v slogu bojne ladje. Tisti. eno vozlišče se nahaja v a1, drugo pa v d5. Še posebej pomaga, da cytoscape naredi objekte na platnu gibljive, tj. lahko jih premikamo, vidimo različne možnosti postavitve in nato popravimo razporeditev elementov, ki so nam všeč v kodi.
Na splošno je razumljivo. Lahko poskusite tudi vi?
Seveda sem si za hitro ustvarjanje vezij naredil majhen , ki sam posodobi shemo in shrani najnovejšo različico v brskalnik (v localStorage).
Ste poskusili? Zdaj ga lahko dodate na svojo stran.
Ampak:
1. Povezovanje skripte
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Dodajte kodo v 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. kodo uredimo v diagram, ki ga potrebujemo (mislim, da je lažje kot risati sovo :)
Več podrobnosti na na githubu.
Kakšen je rezultat?
Dosegel sem svoje cilje - dokumentaciji sem dodal inline diagrame, format je precej preprost in razumljiv. Ni primeren za super vezja, vendar je za majhna vezja, ki pojasnjujejo strukturo povezav, popolnoma v redu. Sčasoma lahko vedno hitro nekaj prilagodite in spremenite. Da, in kolegi lahko sami popravijo nekaj v doku, vsaj napise za predmete, brez posebnega usposabljanja))
Kaj je mogoče izboljšati?
Tu je seveda veliko možnosti. Dodajte dodatne ikone (vse obstoječe so dodane v vrstici skripta). Izberite bolj izrazit niz ikon. Omogočite določitev sloga povezovalne linije. Dodajte sliko za ozadje.
Kaj misliš?
Imam že kar nekaj idej za izvedbo v izdajah, svoje lahko dodate tudi v komentarje.
Moja rešitev je vsekakor uporabna v ozkem obsegu problemov in morda boste našli bolj priročno orodje za risanje diagramov tako, da jih preprosto kodirate - kot pravijo "pokaži mi svoj diagram kot kodo"
- (9 vrst spletnih urejevalnikov grafikonov)
- In če imate radi super podrobne in kompleksne diagrame, potem boste zagotovo občudovali ta projekt:
Vir: www.habr.com