U posljednjih nekoliko godina više se bavim dokumentacijom. Pisanje objašnjavajućeg teksta o tome kako funkcioniše neka ili druga sistema - u suštini, to je dovoljno jednostavno. Nacrtati dijagram koji prikazuje sve ključne objekte i veze između tih objekata također je prilično lako.
Ali najproblematičnija tačka je održavanje ove dokumentacije u ažuriranom stanju. Da je bar tekst u pitanju, ali dijagrami... Pošto je sva dokumentacija online, tj. u HTML formatu, uz tekst su priložene slike gif/jpg/png, na kojima su zapravo prikazani dijagrami. A dijagrami se crtaju u različitim programima poput Visio-a ili online servisima poput draw.io. Zatim se dijagram izvozi u grafički format i prilaže HTML-u. Sve je jednostavno.
U čemu je problem?
Dijagrami su obično jednostavni. Tačnije, nisu previše složeni. Da, broj objekata je desetak-dva, broj veza otprilike toliko. Plus natpisi, neka obeležavanja. Jednostavne dijagrame se može opisati i rečima, a previše složene, hm... (c) 'neće biti razumljivo'. Ima mnogo dijagrama, potrebno je povremeno-menjati ih, tj. stalno, jer idu u korak s razvojem naših proizvoda.
Možeš li ugraditi HTML servisa? Jesi li probavao?
Da, naravno. Meni, na primjer, se sviđaju grafike na gliffy.com. Ali za promjene trebaš otići u spoljni servis, tamo ispraviti. A teže je delegirati kolegi da napravi izmjene.
Šta uraditi?
Nedavno sam na githubu naišao u preporukama na repozitorij . Dijagram kao kod. Tj. opisujemo na js potrebni dijagram. Ovaj js pišemo direktno u istom HTML-u gdje je i ostali tekst dokumentacije.
Usput rečeno, ne pišem dokumentaciju potpuno u HTML-u. Obično je dokumentacija skup fajlova sa markdown tekstom, koji se kasnije konvertuje u potpuni web sajt dokumentacije nekim motorom, na primjer wintersmith. Ili wiki sistem.
Ispada vrlo praktično: napisali smo tekst, zatim se otvara script tag i u njemu je opisan js kod dijagrama.
Šta opet nije u redu?
Ovaj repozitorij mi se dopao, ali to nije jedini primjer kada dijagram crtaju pomoću koda ili tekstualnog prikaza. (Na kraju članka će biti linkova na projekte i članke koje sam pronašao na temu dijagram kao kod.)
I nisam jedini koji se bavi dokumentacijom. Ponekad se i kolege uključe — isprave neku reč, promene opis, dodaju nove slike.
Zato bih voleo da dijagram vidim u čitljivom i razumljivom tekstualnom formatu, koji ne bi zahtevao dugo učenje. A ponekad čak jednostavno kopija-lepljenje da ubrza dodavanje nove šeme.
A jedan kolega je primetio da je kod, naravno, dobar, ali ako se koristi struktura, sve može biti vrlo strogo i ekspresivno.
Zato sam pokušao da predstavim šemu kao skup nekoliko malih nizova koji opisuju čvorove, veze, grupe čvorova, kao i raspored čvorova. Izgleda dovoljno zgodno, iako, naravno, o ukusima se ne raspravlja…
Kako je to dijagram u nizu?
- Svaki čvor se opisuje identifikatorom koji jednoznačno definiše čvor.
- Takođe, čvoru se može dodati ikona, dodati natpis.
- Između dva čvora može se označiti veza.
- Za vezu na šemi može se odrediti boja, natpis.
- Smer veze se određuje od izvora do cilja. A izvor i cilj se označavaju identifikatorima čvora.
- Jedan ili više čvorova može se dodati grupi.
- Veza se takođe može odrediti i od grupe i prema grupi.
Koristeći ova jednostavna pravila, dobijamo ovakvu šemu. Lako? Potpuno.

Ona se opisuje sledećim js kodom. Osnovno ovde — to je objekat elements. U kojem su navedeni nodes — čvorovi, edges — veze.
const elements = {
nodes: [ // opisujemo čvorove
{ id: 'client', type: 'smartphone', label: 'Mobilna aplikacija'},
{ id: 'server', type: 'server', label: 'Glavni server'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [ // navodimo veze
{ source: 'client', target: 'server', label: 'zahtev' },
{ source: 'server', target: 'db1', label: 'zahtev' },
{ source: 'server', target: 'db2', label: 'zahtev' },
],
};
Diagram('scheme1', elements);
Naravno, crtanje šeme nisam smislio sam, već sam se poslužio bibliotekom — vrlo moćnim alatom za vizualizaciju. Od njenog spektra mogućnosti u svom rešenju koristim samo delić.
Jasno, ovo je jednostavan primer. Može li biti složenije?
Da, naravno. Za označavanje pozicija — koristimo positions, za označavanje grupa — navodimo listu grupa u groups, a sami elementi imaju atribut group.

A ovo je kod:
<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>
Ova shema s jedne strane — to su skoro dva ekrana koda na laptopu, a s druge strane struktura slična json-u omogućava brzo popunjavanje svih podataka po analogiji, uz mogućnost copy-paste.
Zašto su pozicije odvojene od čvorova?
Tako je lakše. Prvo navodimo čvorove. Zatim možemo navesti nekoliko grupa i uključiti ih u čvorove. Nakon toga označavamo veze. A tek kada imamo osnovne objekte i veze između njih, uzimamo se za raspored tih objekata na shemi. Ili obrnuto.
Može li i bez pozicija?
Može i bez pozicija. Ali će to biti malo zbunjujuće; u primerima možete videti takvu varijantu. To je zbog toga što za cytoscape postoji algoritam za raspoređivanje čvorova. , koji takođe uzima u obzir prisustvo grupa. Navođenje pozicija čini shemu kontrolisanijom, ali u fazi prvog nacrta sheme može se i bez pozicija.
Takođe, pozicije se mogu navoditi u stilu Morskog boja. Tj. jedan čvor se nalazi u a1, a drugi u d5. Posebno pomaže što cytoscape formira objekte na platnu pokretnima, tj. možemo ih pomerati, razmatrati različite rasporede, a zatim fiksirati u kodu omiljeni raspored elemenata.
U celini, jasno je. Možemo li probati?
Naravno, za brzo kreiranje shema napravio sam sebi mali , koji samostalno ažurira shemu i u pretraživaču čuva poslednju verziju (u localStorage).
Jeste li probali? Sada možete dodati i na svoju stranicu.
Dakle, još jednom:
1. Povezujemo skriptu
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Dodajemo u html kod
<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. prilagodimo kod do potrebne nam sheme (mislim da je ovo lakše nego naslikati sovu 🙂
Još tačnije na na github-u.
Šta na kraju?
Svojih ciljeva sam postigao — napraviti dodavanje shema inline u dokumentaciju, format je dovoljno jednostavan i razumljiv. Za super sheme nije pogodan, ali za male sheme koje objašnjavaju strukturu veza — itekako je dobar. Uvek se može brzo ispraviti i nešto menjati s vremenom. Da, i kolege mogu same nešto ispraviti u dokumentu, bar natpise na objektima bez posebnog obučavanja ))
Šta se može poboljšati?
Ovde, naravno, postoji mnoštvo opcija. Napraviti dodavanje dodatnih ikona (svi postojeći su dodani inline u skriptu). Odabrati izražajniji set ikona. Napraviti mogućnost navođenja stila linije veza. Dodati pozadinsku sliku.
A šta vi mislite?
Već imam nekoliko ideja za implementaciju u issues, slobodno dodajte svoje u komentare.
Moje rešenje je definitivno primenljivo na uskom spektru zadataka, a možda ćete pronaći pogodniji alat za crtanje dijagrama jednostavno ih kodirajući — kao što kažu ‘pokaži mi svoj dijagram kao kod’
- (9 tipova grafikon online uređivač)
- I ako volite super detaljne i složene dijagrame — onda će vas ovaj projekat definitivno oduševiti:
Izvor: habr.com
