U posljednjih nekoliko godina više sam se bavio dokumentacijom. Pisanje teksta s objašnjenjem o tome kako određeni sistem funkcionira općenito je prilično jednostavno. Crtanje dijagrama koji će prikazati sve ključne objekte i veze između ovih objekata je također prilično jednostavno.
Ali najproblematičniji aspekt je ažuriranje ove dokumentacije. I tekst bi bio u redu, ali dijagrami... Jer... sva dokumentacija je online, tj. u html formatu, onda je uz tekst gif/jpeg/png slike, koje zapravo prikazuju dijagrame. A dijagrami se crtaju u raznim programima kao što su Visio ili online servisi a la draw.io. Zatim izvozite dijagram u grafički format i priložite ga html-u. To je jednostavno.
U čemu je problem?
Šeme su obično jednostavne. Tačnije, ne baš komplikovano. Da, broj objekata je desetak ili dva, broj veza je približno isti. Plus potpisi, neke oznake. Jednostavne šeme se mogu opisati riječima, ali previše složene, hm... (c) "neće razumjeti, gospodine." Postoji mnogo shema, potrebno ih je mijenjati periodično, epizodično, tj. stalno, jer prate razvoj naših proizvoda.
Možete ugraditi html servisa. Jeste li probali?
Da naravno. Na primjer, sviđa mi se grafika sa gliffy.com. Ali da biste izvršili promjene, morate otići na uslugu treće strane i tamo urediti. I teže je delegirati ispravke na kolegu.
Što da radim?
Nedavno sam u preporukama naišao na spremište na Githubu . Dijagram kao kod. One. opisujemo kolo koje nam treba u js. Ovaj js pišemo direktno u istom html-u gdje je i drugi tekst dokumentacije.
Inače, pišem dokumentaciju ne u potpunosti u html-u. Tipično, dokumentacija je skup datoteka s tekstom umanjivanja, koji se zatim pretvara u punopravnu stranicu za dokumentaciju od strane nekog motora, na primjer wintersmith-a. Ili wiki sistem.
Ispada vrlo zgodno: napisali smo tekst, zatim se otvara oznaka skripte i u njoj je opisan JS kod šeme.
Šta opet nije u redu?
Svidjelo mi se ovo spremište, ali ovo nije jedini primjer gdje je dijagram nacrtan korištenjem koda ili tekstualnog prikaza. (Na kraju članka će biti veze do projekata i članaka koje sam pronašao na Google dijagramu teme kao kod.)
I nisam jedini koji uređuje dokumentaciju. Ponekad doprinose i kolege - ispravite riječ, promijenite opis, ubacite nove slike.
Stoga bih želio vidjeti dijagram u čitljivom, razumljivom tekstualnom formatu koji ne bi zahtijevao dugu krivulju učenja. A na nekim mjestima čak možete jednostavno kopirati i zalijepiti kako biste ubrzali dodavanje novog kola.
I drugi kolega je primijetio da je kod, naravno, dobar, ali ako koristite strukturu, sve može biti vrlo strogo i izražajno.
Stoga sam pokušao zamisliti dijagram kao skup nekoliko malih nizova koji opisuju čvorove, veze, grupe čvorova, kao i lokaciju čvorova. Ispalo je, po mom skromnom mišljenju, prilično zgodno, iako, naravno, ukus i boja...
Kako je ovo grafikon u nizu?
- Svaki čvor je opisan identifikatorom koji jedinstveno identificira čvor.
- Također možete dodati ikonu u čvor i dodati natpis.
- Možete odrediti odnos između dva čvora.
- Za komunikaciju na dijagramu možete postaviti boju i natpis.
- Smjer komunikacije definiran je od izvora do cilja. A izvor i cilj su naznačeni identifikatorima čvora.
- U grupu se može dodati jedan ili više čvorova.
- Odnos se također može specificirati i iz grupe i za grupu.
Koristeći ova jednostavna pravila, dobijamo sljedeći dijagram. Samo? Sasvim.
I to je opisano sljedećim js kodom. Glavna stvar ovdje su elementi objekt. U kojima su naznačeni čvorovi - čvorovi, ivice - veze.
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);
Naravno, nisam sam smislio crtež kola, već sam koristio biblioteku je vrlo moćan alat za vizualizaciju. Koristim samo djelić mogućnosti u svom rješenju.
U redu, ovo je jednostavan primjer. Može li biti komplikovanije?
Da molim. Za označavanje pozicija koristimo pozicije, za označavanje grupa ukazujemo na listu grupa u grupama, a sami elementi imaju atribut grupe.
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>
S jedne strane, takva shema je gotovo nekoliko ekrana koda na laptopu, s druge strane, struktura a la json vam omogućava da popunite sve podatke po analogiji, brzo i možete kopirati i zalijepiti.
Zašto se pozicije postavljaju odvojeno od čvorova?
Udobnije je. Prvo specificiramo čvorove. Tada možemo odrediti nekoliko grupa i označiti ih u čvorovima. Zatim označavamo veze. I tek tada, kada su glavni objekti i veze između njih tu, preuzimamo lokaciju ovih objekata na dijagramu. Ili obrnuto.
Da li je moguće bez pozicija?
Moguće je i bez pozicija. Ali bit će malo zgužvano; ovu opciju možete vidjeti u primjerima. To je zbog činjenice da postoji algoritam za lokaciju čvorova za cytoscape , koji takođe uzima u obzir prisustvo grupa. Određivanje pozicija čini dijagram upravljivijim, ali u fazi prvog nacrta dijagrama moguće je bez pozicija.
Pozicije se također mogu specificirati u stilu bojnog broda. One. jedan čvor se nalazi u a1, a drugi u d5. Posebno pomaže to što cytoscape čini objekte na platnu pokretnim, tj. možemo ih pomicati, vidjeti različite opcije izgleda, a zatim popraviti raspored elemenata koji nam se sviđaju u kodu.
Generalno, razumljivo je. Možete li i vi probati?
Naravno, da bih brzo stvorio kola, napravio sam sebi mali , koji sam ažurira shemu i pohranjuje najnoviju verziju u pretraživač (u localStorage).
Jeste li probali? Sada ga možete dodati na svoju stranicu.
onda opet:
1. Povezivanje skripte
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Dodajte kod u 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. uređujemo kod u dijagram koji nam treba (mislim da je lakše nego crtati sovu :)
Više detalja na na github-u.
Šta je na kraju?
Postigao sam svoje ciljeve - dodati inline dijagrame u dokumentaciju, format je prilično jednostavan i razumljiv. Nije pogodan za super kola, ali za mala kola koja objašnjavaju strukturu veza, sasvim je u redu. Uvijek možete brzo nešto podesiti i promijeniti s vremenom. Da, i kolege mogu sami nešto ispraviti na doku, barem natpise za objekte, bez posebne obuke))
Šta se može poboljšati?
Ovdje, naravno, postoji mnogo opcija. Dodajte dodatne ikone (sve postojeće se dodaju u skriptu). Odaberite izražajniji skup ikona. Omogućite određivanje stila linije veze. Dodajte sliku za pozadinu.
Šta ti misliš?
Već imam nekoliko ideja za implementaciju u izdanjima, možete dodati i svoje u komentarima.
Moje rješenje je definitivno primjenjivo u uskom rasponu zadataka, a možda ćete pronaći pogodniji alat za crtanje dijagrama jednostavnim kodiranjem - kako kažu 'pokažite mi svoj dijagram kao kod'
- (9 vrsta online uređivača grafikona)
- A ako volite super detaljne i složene dijagrame, onda ćete se sigurno diviti ovom projektu:
izvor: www.habr.com