Viimastel aastatel olen rohkem hakanud tegelema dokumentatsiooniga. Kirjutada selgitavat teksti selle kohta, kuidas mingi süsteem töötab — see on üldiselt üsna lihtne. Joonistada skeem, mis näitab kõiki olulisi objekte ja nendevahelisi seoseid, on samuti täiesti teostatav.
Aga kõige probleemsem hetk on see, et hoida see dokumentatsioon ajakohasena. Ja mitte ainult tekst, vaid ka skeemid... Kuna kogu dokumentatsioon on veebis, st HTML-formaadis, siis teksti juurde kuuluvad gif/jpeg/png pildid, millel skeemid on kujutatud. Skeemid joonistatakse erinevates programmides, nagu Visio või veebiteenustes nagu draw.io. Siis eksportid skeemi graafilisse formaati ja lisad selle HTML-ile. Kõik on piisavalt lihtne.
Mis on probleem?
Skeemid on tavaliselt lihtsad. Täpsemalt, mitte väga keerulised. Jah, objekte on paar tosinat, seoseid umbes sama palju. Lisaks on sildid ja mingid tähistused. Lihtsaid skeeme võib sõnades kirjeldada, aga liiga keerulisi, kh-m... (c) "ei saa aru-s". Skeeme on palju, neid tuleb pidevalt perioodiliselt muuta, st pidevalt, kuna need järgivad meie toodete arendust.
Kas html-teenuseid ei saa integreerida? Proovisid?
Jah, muidugi. Mulle näiteks meeldivad graafikud gliffy.com. Kuid muudatuste tegemiseks tuleb minna kolmandasse teenusesse, seal neid muuta. Ja keerulisem on kolleegile muudatusi anda.
Mida teha?
Hiljuti sattusin Githubis soovitustes kokku haruldase hoidla peale . Diagramm kui kood. St me kirjeldame js-s vajaliku skeemi. Selle js-i kirjutame otse sinna samasse HTML-i, kus on ka muu dokumentatsiooni tekst.
Muide, ma ei kirjutagi dokumentatsiooni täiesti HTML-is. Tavaliselt on dokumentatsioon failide kogum markdown-tekstiga, mis seejärel konverteeritakse täisväärtuslikuks dokumentatsioonisaidiks mingi mootori, näiteks wintersmith, abil. Või wiki-süsteemi kaudu.
See on tõeliselt mugav: oleme kirjutanud teksti, seejärel avatakse script-tag ja seal on kirjas skeemi js-kood.
Mis on taas valesti?
See hoidla meeldis mulle, kuid see pole ainus näide, kui diagrammi joonistatakse koodi või tekstilise esitluse abil. (Artikli lõpus on lingid projektidele ja artiklitele, mille leidsin diagramm koodi teema kohta.)
Ja ma ei pruugi olla ainus, kes dokumentatsiooni toimetab. Mõnikord panustavad ka kolleegid — sõna parandamine, kirjelduse muutmine, uusi pilte lisamine.
Seetõttu sooviksin diagrammi näha loetavas ja arusaadavas tekstivormingus, mille õppimiseks ei peaks kaua aega kulutama. Mõnes kohas võiks isegi lihtsalt copy-paste teha, et uue skeemi lisamist kiirendada.
Ja veel üks kolleeg märkis, et kood on muidugi hea, kuid struktuuri kasutamisel võib kõik olla väga range ja väljendusrikas.
Seetõttu proovisin esitada skeemi kui mitmest väikesest massiivist koosnevat kogumit, mis kirjeldavad sõlmi, seoseid, sõlmede gruppe ning sõlmede asukohta. Minu tagasihoidlikul arvamusel õnnestus see piisavalt mugavalt, kuigi maitsete ja värvide osas...
Kuidas see diagramm massiivis välja näeb?
- Iga sõlm on kirjeldatud identifikaatoriga, mis määratleb sõlme üheselt.
- Samuti saab sõlmele lisada ikooni ja tekstilõigu.
- Kahe sõlme vahel saab näidata seost.
- Seosele skeemis saab määrata värvi ja tekstilõigu.
- Seose suund määratakse allikast sihtpunkti. Allikas ja sihtpunkt käiakse läbi sõlme identifikaatorite abil.
- Üks või mitu sõlme saab lisada gruppi.
- Seost saab samuti näidata nii grupist kui ka gruppi.
Kasutades neid lihtsaid reegleid, saadakse järgmine skeem. Lihtne? Täiesti.
Ja see on kirjeldatud järgmise js-koodiga. Peamine siin on objekt elements, kus on märgitud nodes — sõlmed, edges — seosed.
const elements = {
nodes: [ // kirjeldame sõlmi
{ 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: [ // määratleme seosed
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
Muidugi ei väljamõelnud ma skeemi joonistamist ise, vaid kasutasin teeki — väga võimas visualiseerimistööriist. Selle võimaluste kätkeb oleksin oma lahenduses kasutusele vaid osa.
Selge, see on lihtne näide. Kas võib keerulisemat?
Jah, palun. Positsioonide näitamiseks kasutame positions, gruppide näitamiseks loetleme gruppide nimekirja groups-is, ning elementidel endil on attribuut group.
Ja see on kood:
<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>
Seda skeemi vaadates — see on peaaegu kaks ekraanitäit koodi sülearvutis, teisest küljest json-laadne struktuur võimaldab kõik andmed kiirelt ja lihtsalt sisestada, samuti copy-paste.
Aga miks on positions eraldi sõlmedest välja toodud?
Nii on mugavam. Esiteks määrame nodes. Siis saame määrata paar gruppi ja lisada need sõlmedesse. Seejärel tähistame seosed. Ja kui põhiobjektid ja seosed nende vahel on olemas, hakkame tegelema nende objektide paigutamisega skeemil. Või vastupidi.
Kas saab ka ilma positions'ta?
Saab ka ilma positions'ta. Aga see tuleb veidi segamini, näidistes võib sellised variandid näha. See on tingitud sellest, et cytoscape'ile on olemas sõlmede paigutamise algoritm , mis arvestab ka rühmade olemasolu. Positions'i määramine muudab skeemi paremini kontrollitavaks, kuid skeemi esialgse mustandi faasis võib see olla ka ilma positions'ta.
Samuti saab positions'e määrata meresõda stiilis. St. üks sõlm asub a1 ja teine d5. Eriti aitab see, et cytoscape kujundab objektid canvase all liikuvatena, st. me saame neid liigutada, vaadata erinevaid paigutuse variante ja siis kinnitada koodis meelepärase paigutuse elementide jaoks.
Üldiselt on arusaadav. Kas saame proovida?
Loomulikult, et kiirelt skeeme luua, tegin endale väikese , mis uuendab skeemi ise ja salvestab brauseris viimase variandi (localStorage'is).
Kas oled proovinud? Nüüd saab ka enda lehele lisada.
Siis veel kord:
1. Ühendame skripti
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Lisame HTML koodi
<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. muudame koodi meie soovitud skeemiks (ma arvan, et see on lihtsam kui öökulli joonistamine 🙂
Veelgi üksikasjalikumalt GitHub'is.
Kokkuvõttes?
Oma eesmärke saavutasin — teha skeemide lisamine inline dokumentatsioonis, formaat on piisavalt lihtne ja arusaadav. Super-skeemide jaoks ei sobi, aga väikeste skeemide jaoks, mis selgitavad seoste struktuuri — on see väga hea. Alati saab kiiresti midagi kohandada ja ajaga muuta. Jah, ja kolleegid saavad dokumendis midagi ise kohandada, vähemalt objekti tähised ilma eriliku koolituseta ))
Mis võiks paremaks minna?
Siin on muidugi hulgaliselt variante. Lisada täiendavaid ikoonide (kõik olemasolevad on skripti sisse lisatud). Leida rohkem väljendusrikkam ikoonide komplekt. Luua võimalus määrata seose joonte stiil. Lisada taustapilt.
Kuidas teie arvate?
Mul on juba mitu ideed ellu viimiseks issues, lisage ka enda omasid kommentaaridesse.
Minu lahendus on kindlasti rakendatav kitsas ülesannete spektris, ja võib-olla leiate mugavama diagrammide joonistamise tööriista, lihtsalt koodides neid — nagu öeldakse, 'näita mulle oma diagrammi koodina'
- (9 tüüpi graafikuid veebiredaktoris)
- Ja kui teile meeldib ülimalt detailne ja keeruline skeem — siis see projekt kindlasti teid inspireerib:
Allikas: habr.com
