Gjatë viteve të fundit, fillova të angazhohem më shumë me dokumentacionin. Të shkruash një tekst shpjegues për mënyrën se si funksionon një sistem i caktuar — në thelb, është mjaft e lehtë. Të vizatosh një skemë që tregon të gjitha objektet kyçe dhe lidhjet midis tyre është gjithashtu mjaft e thjeshtë.
Por problemi më i madh është se si ta mbash këtë dokumentacion të përditësuar. Dhe le të ishte vetëm teksti, por skemat… Duke qenë se e gjithë dokumentacioni është online, pra në formatin html, teksti shoqërohet me imazhe gif/jpeg/png, të cilat përshkruajnë skemat. Skemat çizohen në programe të ndryshme si Visio ose shërbime online si draw.io. Pastaj eksporton skemën në format grafik dhe e bashkangjit në html. Të gjitha janë të thjeshta.
Cila është problemi?
Skemat janë zakonisht të thjeshta. Më saktë, nuk janë shumë të ndërlikuara. Po, numri i objekteve është njëzet deri në tridhjetë, numri i lidhjeve është afërsisht i njëjtë. Plus, ka etiketa dhe disa shenja. Skemat e thjeshta mund të përshkruhen edhe me fjalë, por ato që janë shumë të ndërlikuara, khem... (c) "nuk do të kuptohen." Ka shumë skema, dhe ne duhet të bëjmë ndryshime në to periodikisht, pra vazhdimisht, sepse ato ndjekin zhvillimin e produkteve tanë.
A nuk mund të integrohen shërbimet HTML? E ke provuar?
Po, natyrisht. Mua, për shembull, më pëlqejnë grafikët e gliffy.com. Por për ndryshime, duhet të shkojmë në një shërbim të jashtëm, atje për të korrigjuar. Dhe është më e vështirë të delegosh për të bërë ndryshime për kolegun.
Çfarë të bëjmë?
Së fundmi, më doli në rekomandimet në GitHub një depo . Grafika si kod. Pra, ne e përshkruajmë skemën tonë të nevojshme në js. Ky js e shkruajmë në të njëjtin HTML ku ndodhet dhe teksti tjetër i dokumentacionit.
Për ta thënë, por unë nuk e shkruaj dokumentacionin krejt në HTML. Zakonisht dokumentacioni është një grup skedash me tekst markdown, i cili më pas konvertohet në një faqe komplekse dokumentacioni me ndihmën e ndonjë motorri, si wintersmith. Ose sistemi wiki.
Shkruajmë një tekst, pastaj hapim tag-un script ku përshkruhet kodi js i diagramës.
Çfarë nuk është në rregull përsëri?
Më pëlqeu ky depo, por nuk është shembulli i vetëm kur një diagram vizatohet përmes kodit ose të dhënave tekstuale. (Në fund të artikullit do të ketë lidhje me projekte dhe artikuj që kam gjetur për temën diagram si kod.)
Dhe nuk jam vetëm unë që redaktoj dokumentacionin. Ndonjëherë kolegët e mi kontribuojnë — për të korrigjuar ndonjë fjalë, për të ndryshuar një përshkrim, për të shtuar imazhe të reja.
Prandaj do të doja të shihja diagramin në një format tekstual të lexueshëm dhe të kuptueshëm, për të cilin nuk do të duhet të mësohem gjatë. E në disa raste, thjesht të bëj copy-paste për të ndihmuar në shtimin e një diagrami të ri.
Një koleg tjetër vuri re se kodi është, sigurisht, i mirë, por nëse përdoret struktura, gjithçka mund të jetë shumë e strukturuar dhe shprehëse.
Kështu, përpiqesha ta paraqes diagramën si një grup disa masivash të vogla që përshkruajnë nyjat, lidhjet, grupet e nyjave, si dhe pozitat e nyjave. Më duket se është mjaft i përshtatshëm, edhe pse, sigurisht, për shije dhe ngjyrë…
Si është kjo diagram në masiv?
- Çdo nyje përshkruhet nga një identifikues që e përcakton qartë atë.
- Gjithashtu, mund të shtoni një ikonë në nyje, si dhe një etiketë.
- Mund të përcaktoni një lidhje midis dy nyjeve.
- Për lidhjen në skemë, mund të caktoni ngjyrën dhe etiketën.
- Drejtimi i lidhjes përcaktohet si nga burimi deri te destinacioni. Burimi dhe destinacioni caktohen me identifikuesit e nyjeve.
- Një ose më shumë nyje mund të shtohen në grup.
- Lidhja gjithashtu mund të përcaktohet nga grupi dhe te grupi.
Duke përdorur këto rregulla të thjeshta, merrni një skemë të tillë. E thjeshtë? Po, mjaft.
Ajo përshkruhet me kodin js si më poshtë. E rëndësishme këtu është objekti elements. Në të janë të caktuara nodes - nyjet, edges - lidhjet.
const elements = {
nodes: [ // përshkruajmë nyjet
{ 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: [ // përcaktojmë lidhjet
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
Sigurisht, skicimin e skemës nuk e kam shpikur vetë, por kam përdorur një bibliotekë. — një mjet shumë i fuqishëm vizualizimi. Vetëm një pjesë e mundësive të saj përdor në zgjidhjen time.
E kuptoj, ky është një shembull i thjeshtë. A mund të jetë më i komplikuar?
Po, sigurisht. Për t'u përcaktuar pozitat — ne përdorim positions, për të përcaktuar grupet — ne shënojmë listën e grupeve në groups, dhe për vetë elementet kemi atributin group.
Ja kodi:
<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>
Një skemë e tillë në një anë — është pothuajse një çift ekranesh kodi në laptop, ndërsa struktura e tipit json lejon mbushjen e të dhënave në një mënyrë të ngjashme, shpejt dhe mund të përdoret copy-paste.
Pse pozitat janë veçuar nga nyjat?
Është më e leverdishme. Së pari, ne përcaktojmë nodes. Më pas mund të shënojmë disa grupe dhe t'i përfshijmë ato në nyja. Pastaj, përcaktojmë lidhjet. Dhe vetëm atëherë, kur objektet kryesore dhe lidhjet midis tyre janë të pranishme, fillojmë me vendosjen e këtyre objekteve në skemë. Ose përkundrazi.
A ka mundësi pa pozita?
Mund të funksionojë edhe pa pozita. Por kjo do të jetë paksa e ngjeshur, në shembuj mund të shihni një variant të tillë. Kjo është për shkak se për cytoscape ekziston një algoritëm për vendosjen e nyjave, , i cili gjithashtu merr parasysh praninë e grupeve. Përcaktimi i pozita bën skemën më të kontrollueshme, por në fazën e parë të skicës së skemës mund të funksionojë edhe pa pozita.
Pozitat e mund të specifikohen gjithashtu në stilin e lojës së detit. Kështu, një nyje është vendosur në a1, ndërsa tjetra në d5. Sidomos ndihmon që cytoscape formon objekte në canvas në lëvizje, pra mund t’i zhvendosim, të shohim variante të ndryshme të vendosjes, e pastaj ta konfirmojmë në kod pozitat e dëshiruara.
Në përgjithësi, e kuptueshme. A mund të provojmë?
Sigurisht, për të krijuar shpejt skema, bëra një , i cili auto-aktualizon skemën dhe ruan variantin e fundit në shfletues (në localStorage).
A e provuat? Tani mund ta shtoni edhe në faqen tuaj.
Atëherë përsëri:
1. Lidhim skriptin
<script src="https://unpkg.com/@antirek/network-diagram@0.1.4/dist/code-full.min.js"></script>
2. Shtojmë në kodin 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. e modifikojmë kodin deri në skemën që na nevojitet (mendoj se është më e thjeshtë se sa të vizatosh një bufnitë 🙂
Më shumë detaje në në github.
Çfarë doli përfundimisht?
Kam arrita objektivat e mia — të shtoj skemat inline në dokumentacion, formati është mjaft i thjeshtë dhe i kuptueshëm. Nuk është i përshtatshëm për super skemat, por për skemat e vogla që shpjegojnë strukturën e lidhjeve — është shumë e dobishme. Gjithmonë mund të bësh disa korrektime të shpejta dhe të ndryshosh diçka me kalimin e kohës. Po, dhe kolegët mund të bëjnë disa ndryshime në dokument, të paktën nënshkruhet nga objektet pa ndonjë mësim të veçantë ))
Çfarë mund të përmirsojmë?
Këtu ka shumë mundësi, sigurisht. Të shtojmë ikona të tjera (të gjitha ekzistuese janë shtuar inline në skript). Të përzgjedhim një set më të shprehshëm ikonash. Të ofrojmë mundësinë e caktimit të stilit të linjave të lidhjeve. Të shtojmë një imazh sfondi.
Çfarë mendoni ju?
Kam disa ide për të implementuar në çështje, ju gjithashtu shtoni tuajat në komente.
Zgjidhja ime është patjetër e aplikueshme në një spektrin të ngushtë detyrash, dhe ndoshta do të gjeni një mjet më të përshtatshëm për të vizatuar diagrame, thjesht duke i koduar ato — siç thotë shprehja ‘tregoni diagramin tuaj si kod’
- (9 lloje grafikësh redaktor online)
- Dhe nëse ju pëlqejnë diagramet super të detajuara dhe komplekse — ky projekt me siguri do t'ju mahnitë:
Burimi: habr.com
