Poslednjih godina sve više se bavim dokumentacijom. Napisati objašnjenje o tome kako funkcioniše neka ili druga sistema — u suštini, to nije tako komplikovano. Nacrtati dijagram koji prikazuje sve ključne objekte, veze između ovih objekata, takođe nije previše teško.
Ali najproblematičnija stvar — održavanje ove dokumentacije ažurnom. I dobro bi bilo samo sa tekstom, ali dijagrami… Pošto je sva dokumentacija online, tj. u HTML formatu, uz tekst prate slike u gif/jpg/png formatima koje zapravo prikazuju dijagrame. Dijagrami se crtaju u raznim programima poput Visio-a ili online servisima sličnim draw.io. Zatim se izveze dijagram u grafički format i prikači uz HTML. Sve je jednostavno.
Gde 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 obeležja i izjave. Jednostavne dijagrame može se opisati i rečima, a previše složene, hm… (s) 'neće razumeti'. Ima puno dijagrama, promene u njima treba povremeno unositi, tj. neprekidno, jer prate razvoj naših proizvoda.
Možeš li ugraditi HTML servis? Da li si pokušao?
Da, naravno. Na primer, sviđa mi se grafika na gliffy.com. Ali za izmene treba ići u spoljašnji servis, tamo napraviti izmene. I teže je delegirati kolegi da napravi ispravke.
Kaj narediti?
Nedavno sam na GitHubu video repozitorijum koji mi je preporučen . Dijagram kao kod. Tj. opisujemo na JS potrebni dijagram. Ovaj JS pišemo direktno u istom HTML-u gde je i ostali tekst dokumentacije.
Usput, ja pišem dokumentaciju ne baš u HTML-u. Obično je dokumentacija skup fajlova sa markdown tekstom, koji se zatim konvertuje u kompletan sajt dokumentacije nekim pokretačem, kao što je wintersmith. Ili wiki-sistem.
Izgleda vrlo praktično: napisali smo tekst, zatim se otvori tag i u njemu je opisan JS kod dijagrama.
Šta ponovno nije u redu?
Ovaj repozitorijum mi se dopao, ali to nije jedini primer kada se dijagram crta pomoću koda ili tekstualnog prikaza. (Na kraju članka biće linkova na projekte i članke koje sam pronašao na temu dijagram kao kod.)
In fact, I am not the only one editing the documentation. Sometimes my colleagues also contribute — correcting words, changing descriptions, inserting new images.
Therefore, I would like to see the diagram in a clear, understandable text format that wouldn't require long training. In some cases, it would be sufficient just to copy-paste to speed up the addition of new schemes.
Another colleague noted that while code is good, if a structure is used, everything can be very precise and expressive.
So I tried to represent the scheme as a set of several small arrays that describe the nodes, connections, groups of nodes, and the positioning of the nodes. In my humble opinion, it turned out to be quite convenient, although, of course, taste varies.
How is this diagram represented in an array?
- Each node is described by an identifier that uniquely defines it.
- You can also add an icon to the node and include a label.
- A connection can be specified between two nodes.
- For the connection in the scheme, you can set a color and a label.
- The direction of the connection is defined from the source to the target. The source and target are indicated by node identifiers.
- One or more nodes can be added to a group.
- The connection can also be specified from a group and to a group.
Using these simple rules, you get such a scheme. Simple? Quite.
It is described by the following js code. The main part here is the elements object, which specifies nodes and edges.
const elements = {
nodes: [ // describing 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: [ // specifying connections
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
Of course, I didn't come up with the drawing of the scheme myself; I used a library. — a very powerful visualization tool, of which I only utilize a fraction of the possibilities in my solution.
It's clear, this is a simple example. Can we make it more complex?
Yes, of course. To specify positions, we use positions, to indicate groups — we define a list of groups in groups, and each element has the group attribute.
And here is the code:
<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>
Ta shema na en strani — to je skoraj par ekranov kode na prenosniku, na drugi strani pa struktura a la json omogoča hitro izpolnjevanje vseh podatkov po analogiji, kar omogoča kopiranje in lepljenje.
Zakaj so pozicije ločene od vozlišč?
Tako je lažje. Najprej navedemo vozlišča. Nato lahko navedemo par ali tri skupine in jih vključimo v vozlišča. Potem označimo povezave. In šele nato, ko so osnovni objekti in povezave med njimi določeni, se lotimo postavitve teh objektov na shemi. Ali obratno.
Ali je mogoče brez pozicij?
Seveda, brez pozicij je mogoče. Ampak to bo nekoliko zmedeno, v primerih si lahko ogledate to varianto. To je posledica dejstva, da za cytoscape obstaja algoritem za postavitev vozlišč. , ki prav tako upošteva prisotnost skupin. Navedba pozicij naredi shemo bolj obvladljivo, vendar lahko v prvi skici sheme greste tudi brez pozicij.
Prav tako je mogoče pozicije določiti v slogu pomorske bitke. T.j. en vozel se nahaja v a1, drugi pa v d5. Še posebej pomaga, da cytoscape oblikuje objekte na platnu tako, da so premični, t.j. jih lahko premikamo, gledamo različne možnosti postavitve in nato v kodi zabeležimo željeno postavitev elementov.
Na splošno, razumem. Lahko poskusimo?
Seveda, za hitro ustvarjanje shem sem si naredil majhen , ki sam posodablja shemo in v brskalniku hrani zadnjo različico (v localStorage).
Ste poskusili? Zdaj ga lahko dodate na svojo stran.
Potem še enkrat:
1. Priključimo skripto
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Dodamo v html kodo
<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. popravimo kodo do želene sheme (mislim, da je to lažje kot narišati sovo 🙂
Še bolj podrobno na na githubu.
Kaj na koncu?
Svojih ciljev sem dosegel — narediti dodajanje shem inline v dokumentacijo, format je dovolj preprost in razumljiv. Ni primeren za super sheme, ampak za manjše sheme, ki pojasnjujejo strukturo povezav — je precej dober. Vedno se ga lahko hitro popravi in kaj sčasoma spremeni. Da, in kolegi lahko v dokumentaciji sami kaj popravijo, vsaj oznake objektov brez posebnega usposabljanja ))
Kaj bi lahko izboljšali?
Tukaj je seveda neskončno možnosti. Dodati dodatne ikone (vse obstoječe so dodane inline v skripto). Izbrati bolj izrazit niz ikon. Omogočiti določanje stila linij povezav. Dodati ozadje.
Kaj menite vi?
Imam već nekoliko ideja za realizaciju u issues, takođe dodajte svoje u komentare.
Moje rešenje je definitivno primenljivo u užem spektru zadataka, i možda ćete naći prikladniji alat za crtanje dijagrama jednostavno kodirajući ih — kako se kaže 'prikažite mi svoj dijagram kao kod'
- (9 tipova grafikona online urednika)
- I ako volite super detaljne i složene sheme — ovaj projekat će vas definitivno oduševiti:
Izvor: habr.com
