Á síðustu tveimur árum hef ég tekið meiri þátt í skjölum. Að skrifa skýringartexta um hvernig þetta eða hitt kerfið virkar er almennt frekar einfalt. Það er líka frekar auðvelt að teikna skýringarmynd sem sýnir alla lykilhluti og tengingar á milli þessara hluta.
En erfiðasti þátturinn er að halda þessum skjölum uppfærðum. Og textinn væri fínn, en skýringarmyndirnar... Vegna þess... öll skjöl eru á netinu, þ.e. á html formi, þá fylgja textanum gif/jpeg/png myndir sem sýna í raun skýringarmyndirnar. Og skýringarmyndir eru teiknaðar í ýmsum forritum eins og Visio eða netþjónustu a la draw.io. Síðan flytur þú skýringarmyndina út í grafískt snið og festir hana við html. Það er einfalt.
Hvað er vandamálið?
Áætlanir eru yfirleitt einfaldar. Nánar tiltekið, ekki mjög flókið. Já, fjöldi hluta er tugur eða tveir, fjöldi tenginga er um það bil sá sami. Plús undirskriftir, nokkrar merkingar. Hægt er að lýsa einföldum áætlunum með orðum, en of flóknum, ahem... (c) "þeir munu ekki skilja, herra." Það eru mörg áætlanir, það þarf að gera breytingar á þeim með reglulegu millibili, tímabundnum, þ.e. stöðugt, vegna þess þeir fylgjast með þróun vara okkar.
Þú getur fellt inn html þjónustunnar. Hefurðu prófað það?
Já að sjálfsögðu. Til dæmis, mér líkar við grafíkina frá gliffy.com. En til að gera breytingar þarftu að fara í þjónustu þriðja aðila og breyta þar. Og það er erfiðara að framselja leiðréttingar til samstarfsmanns.
Hvað á að gera?
Nýlega rakst ég á geymslu á Github í ráðleggingunum . Skýringarmynd sem kóða. Þeir. við lýsum hringrásinni sem við þurfum í js. Við skrifum þetta js beint í sama html þar sem hinn skjalatextinn er.
Við the vegur, ég skrifa skjöl ekki alveg í html. Venjulega eru skjöl sett af skrám með markdown-texta, sem síðan er breytt í fullgilda skjalasíðu af einhverri vél, til dæmis wintersmith. Eða wiki kerfi.
Það reynist mjög þægilegt: við höfum skrifað textann, þá opnast skriftumerkið og JS kóða kerfisins er lýst í því.
Hvað er aftur að?
Mér líkaði við þessa geymslu, en þetta er ekki eina dæmið þar sem skýringarmynd er teiknuð með kóða eða textaframsetningu. (Í lok greinarinnar verða tenglar á verkefni og greinar sem ég gúglaði um efnismyndina sem kóða.)
Og ég er ekki sá eini sem ritstýrir skjölunum. Stundum leggja samstarfsmenn líka sitt til - leiðrétta orð, breyta lýsingu, setja inn nýjar myndir.
Þess vegna myndi ég vilja sjá skýringarmyndina á læsilegu, skiljanlegu textasniði sem myndi ekki krefjast langrar námsferil. Og á sumum stöðum geturðu jafnvel einfaldlega copy-paste til að flýta fyrir að bæta við nýrri hringrás.
Og annar samstarfsmaður tók fram að kóði er auðvitað góður, en ef þú notar uppbyggingu getur allt verið mjög strangt og svipmikið.
Þess vegna reyndi ég að ímynda mér skýringarmyndina sem safn af nokkrum litlum fylkjum sem lýsa hnútum, tengingum, hópum hnúta, sem og staðsetningu hnúta. Það reyndist, að mínu hógværa mati, nokkuð þægilegt, þó auðvitað bragðið og liturinn...
Hvernig er þetta graf í fylki?
- Hverjum hnút er lýst með auðkenni sem auðkennir hnútinn einstaklega.
- Þú getur líka bætt við tákni við hnútinn og bætt við áletrun.
- Þú getur tilgreint tengsl milli tveggja hnúta.
- Fyrir samskipti á skýringarmyndinni geturðu stillt litinn og áletrunina.
- Samskiptastefnan er skilgreind sem frá upptökum til skotmarks. Og uppspretta og skotmark eru auðkennd með hnútaauðkennum.
- Hægt er að bæta einum eða fleiri hnútum við hóp.
- Einnig er hægt að tilgreina tengslin bæði frá hópnum og til hópsins.
Með því að nota þessar einföldu reglur fáum við eftirfarandi skýringarmynd. Bara? Alveg.
Og því er lýst með eftirfarandi js kóða. Aðalatriðið hér er hlutirnir hlut. Þar sem hnútar eru sýndir - hnútar, brúnir - tengingar.
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);
Auðvitað kom ég ekki sjálfur með teikninguna af hringrásinni heldur notaði bókasafnið er mjög öflugt sjónrænt tól. Ég nota aðeins brot af möguleikunum í lausninni minni.
Allt í lagi, þetta er einfalt dæmi. Getur það verið flóknara?
Já endilega. Til að gefa til kynna stöður notum við stöður, til að gefa til kynna hópa, tilgreinum við lista yfir hópa í hópum og frumefnin sjálfir hafa hópeiginleika.
Og þetta er kóðinn:
<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>
Annars vegar er slíkt kerfi næstum nokkrir skjáir af kóða á fartölvu, hins vegar gerir uppbyggingin a la json þér kleift að fylla út öll gögn á hliðstæðan hátt, fljótt og þú getur copy-paste.
Af hverju eru stöður settar aðskildar frá hnútum?
Það er þægilegra. Fyrst tilgreinum við hnúta. Þá getum við tilgreint nokkra hópa og tilgreint þá í hnútum. Síðan tilgreinum við tengingarnar. Og aðeins þá, þegar helstu hlutir og tengingar á milli þeirra eru til staðar, tökum við á okkur staðsetningu þessara hluta á skýringarmyndinni. Eða öfugt.
Er það mögulegt án staða?
Það er hægt án staða. En það verður svolítið krumpað; þú getur séð þennan möguleika í dæmunum. Þetta er vegna þess að það er til reiknirit fyrir staðsetningu hnúta fyrir frumumynd , sem tekur einnig tillit til tilvistar hópa. Að tilgreina staðsetningar gerir skýringarmyndina stýranlegri, en á stigi fyrstu uppkasts skýringarmyndarinnar er mögulegt án staðsetningar.
Einnig er hægt að tilgreina stöður í Battleship stílnum. Þeir. annar hnúturinn er staðsettur í a1 og hinn í d5. Sérstaklega hjálpar það að cytoscape gerir hlutina á striganum hreyfanlega, þ.e. við getum fært þá um, séð mismunandi útsetningarvalkosti og lagað síðan uppröðun þeirra þátta sem okkur líkar við í kóðanum.
Almennt séð er það skiljanlegt. Þú getur líka prófað?
Auðvitað, til að búa til hringrás fljótt, gerði ég mér lítið , sem sjálft uppfærir skemað og geymir nýjustu útgáfuna í vafranum (í localStorage).
Hefurðu prófað það? Þú getur nú bætt því við síðuna þína.
Svo aftur:
1. Tengist handritið
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Bættu kóða við 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. við breytum kóðanum í skýringarmyndina sem við þurfum (ég held að það sé auðveldara en að teikna uglu :)
Nánari upplýsingar á á github.
Niðurstaðan?
Ég náði markmiðum mínum - að bæta innbyggðum skýringarmyndum við skjölin, sniðið er frekar einfalt og skiljanlegt. Það er ekki hentugur fyrir ofurrásir, en fyrir litlar hringrásir sem útskýra uppbyggingu tenginga er það alveg í lagi. Þú getur alltaf fljótt lagfært og breytt einhverju með tímanum. Já, og samstarfsmenn geta sjálfir leiðrétt eitthvað í bryggjunni, að minnsta kosti myndatexta fyrir hluti, án sérstakrar þjálfunar))
Hvað má bæta?
Hér eru auðvitað margir möguleikar. Bættu við viðbótartáknum (öllum þeim sem fyrir eru er bætt inn í handritið). Veldu meira svipmikið sett af táknum. Gerðu það mögulegt að tilgreina stíl tengilínunnar. Bættu við bakgrunnsmynd.
Hvað finnst þér?
Ég er nú þegar með nokkrar hugmyndir að útfærslu í málaflokkum, þú getur líka bætt þínum við í athugasemdum.
Lausnin mín á örugglega við í þröngum sviðum vandamála og ef til vill finnurðu þægilegra tól til að teikna skýringarmyndir með því einfaldlega að kóða þær - eins og sagt er "sýndu mér skýringarmyndina þína sem kóða"
- (9 tegundir af myndritum á netinu)
- Og ef þér líkar mjög ítarlegar og flóknar skýringarmyndir, þá muntu örugglega dást að þessu verkefni:
Heimild: www.habr.com