Negli ultimi due anni sono stato maggiormente coinvolto nella documentazione. Scrivere un testo esplicativo su come funziona questo o quel sistema è generalmente abbastanza semplice. Anche disegnare un diagramma che mostrerà tutti gli oggetti chiave e le connessioni tra questi oggetti è abbastanza semplice.
Ma l’aspetto più problematico è mantenere aggiornata questa documentazione. E il testo andrebbe bene, ma i diagrammi... Perché... tutta la documentazione è online, ad es. in formato html, poi il testo è accompagnato da immagini gif/jpeg/png, che mostrano effettivamente i diagrammi. E i diagrammi vengono disegnati in vari programmi come Visio o servizi online come la draw.io. Quindi esporti il diagramma in formato grafico e lo alleghi in html. È semplice.
Qual è il problema?
Gli schemi sono generalmente semplici. Più precisamente, non molto complicato. Sì, il numero di oggetti è una dozzina o due, il numero di connessioni è approssimativamente lo stesso. Più firme, alcune designazioni. Gli schemi semplici possono essere descritti a parole, ma quelli troppo complessi, ehm... (c) “non capiranno, signore”. Esistono molti schemi, è necessario apportare modifiche periodicamente, episodicamente, ad es. costantemente, perché seguono lo sviluppo dei nostri prodotti.
Puoi incorporare l'html del servizio. L'hai provato?
Si certo. Ad esempio, mi piace la grafica di gliffy.com. Ma per apportare modifiche, devi accedere a un servizio di terze parti e modificarlo lì. Ed è più difficile delegare le correzioni a un collega.
Cosa fare?
Recentemente mi sono imbattuto in un repository su Github nei consigli . Diagramma come codice. Quelli. descriviamo il circuito di cui abbiamo bisogno in js. Scriviamo questo js direttamente nello stesso html in cui si trova l'altro testo di documentazione.
A proposito, scrivo la documentazione non interamente in html. In genere, la documentazione è un insieme di file con testo di markdown, che viene poi convertito in un sito di documentazione a tutti gli effetti da qualche motore, ad esempio Wintersmith. O un sistema wiki.
Risulta molto conveniente: abbiamo scritto il testo, quindi si apre il tag script e in esso è descritto il codice JS dello schema.
Cosa c'è di sbagliato di nuovo?
Mi è piaciuto questo repository, ma non è l'unico esempio in cui un diagramma viene disegnato utilizzando codice o una rappresentazione testuale. (Alla fine dell'articolo ci saranno collegamenti a progetti e articoli che ho cercato su Google sul diagramma dell'argomento come codice.)
E non sono l’unico a modificare la documentazione. A volte anche i colleghi contribuiscono: correggi una parola, modifica una descrizione, inserisci nuove immagini.
Pertanto, mi piacerebbe vedere il diagramma in un formato di testo leggibile e comprensibile che non richieda una lunga curva di apprendimento. E in alcuni punti puoi anche semplicemente copiare e incollare per velocizzare l'aggiunta di un nuovo circuito.
E un altro collega ha notato che il codice, ovviamente, è buono, ma se usi la struttura, tutto può essere molto rigoroso ed espressivo.
Pertanto, ho provato a immaginare il diagramma come un insieme di diversi piccoli array che descrivono nodi, connessioni, gruppi di nodi, nonché la posizione dei nodi. Si è rivelato, a mio modesto parere, abbastanza conveniente, anche se, ovviamente, il gusto e il colore...
Come è questo un grafico in un array?
- Ogni nodo è descritto da un identificatore che identifica univocamente il nodo.
- Puoi anche aggiungere un'icona al nodo e aggiungere un'iscrizione.
- È possibile specificare una relazione tra due nodi.
- Per la comunicazione sul diagramma, è possibile impostare il colore e l'iscrizione.
- La direzione della comunicazione è definita dalla sorgente alla destinazione. E la sorgente e la destinazione sono indicate dagli identificatori del nodo.
- È possibile aggiungere uno o più nodi a un gruppo.
- La relazione può anche essere specificata sia dal gruppo che verso il gruppo.
Usando queste semplici regole, otteniamo il seguente diagramma. Appena? Abbastanza.
Ed è descritto dal seguente codice js. La cosa principale qui è l'oggetto elementi. In cui sono indicati i nodi - nodi, bordi - connessioni.
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);
Naturalmente, non ho inventato io stesso il disegno del circuito, ma ho utilizzato la biblioteca è uno strumento di visualizzazione molto potente. Utilizzo solo una frazione delle possibilità nella mia soluzione.
Ok, questo è un semplice esempio. Può essere più complicato?
Sì grazie. Per indicare le posizioni, usiamo posizioni, per indicare i gruppi, indichiamo un elenco di gruppi in gruppi e gli elementi stessi hanno un attributo di gruppo.
E questo è il codice:
<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>
Da un lato, un tale schema è quasi un paio di schermate di codice su un laptop, dall'altro la struttura à la json ti consente di compilare tutti i dati per analogia, rapidamente e puoi copiarli e incollarli.
Perché le posizioni vengono posizionate separatamente dai nodi?
È più comodo. Per prima cosa specifichiamo i nodi. Quindi possiamo specificare un paio di gruppi e indicarli nei nodi. Quindi designiamo le connessioni. E solo allora, quando sono presenti gli oggetti principali e le connessioni tra loro, assumiamo la posizione di questi oggetti sul diagramma. O vice versa.
È possibile senza posizioni?
È possibile senza posizioni. Ma sarà un po' accartocciato; puoi vedere questa opzione negli esempi. Ciò è dovuto al fatto che esiste un algoritmo per la localizzazione dei nodi nel citoscape , che tiene conto anche della presenza di gruppi. Specificare le posizioni rende il diagramma più controllabile, ma nella fase della prima bozza del diagramma è possibile senza posizioni.
Le posizioni possono anche essere specificate nello stile Corazzata. Quelli. un nodo si trova in a1 e l'altro in d5. Aiuta soprattutto il fatto che il citoscape renda mobili gli oggetti sulla tela, ad es. possiamo spostarli, vedere diverse opzioni di layout e quindi correggere la disposizione degli elementi che ci piacciono nel codice.
In generale, è comprensibile. Puoi anche provare?
Naturalmente, per creare velocemente dei circuiti, me ne sono fatto un piccolo , che a sua volta aggiorna lo schema e memorizza la versione più recente nel browser (in localStorage).
L'hai provato? Ora puoi aggiungerlo alla tua pagina.
Poi di nuovo:
1. Collegamento della sceneggiatura
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Aggiungi codice all'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. modifichiamo il codice nel diagramma di cui abbiamo bisogno (penso che sia più semplice che disegnare un gufo :)
Maggiori dettagli su su github.
Il risultato?
Ho raggiunto i miei obiettivi: aggiungere diagrammi in linea alla documentazione, il formato è abbastanza semplice e comprensibile. Non è adatto per i supercircuiti, ma per i piccoli circuiti che spiegano la struttura delle connessioni va assolutamente bene. Puoi sempre modificare e cambiare rapidamente qualcosa nel tempo. Sì, e i colleghi possono correggere da soli qualcosa sul banco degli imputati, almeno le didascalie per gli oggetti, senza una formazione speciale))
Cosa si può migliorare?
Naturalmente ci sono molte opzioni qui. Aggiungi icone aggiuntive (tutte quelle esistenti vengono aggiunte in linea allo script). Scegli un set di icone più espressivo. Rende possibile specificare lo stile della linea di connessione. Aggiungi un'immagine di sfondo.
Che ne pensi?
Ho già diverse idee da implementare nei numeri, puoi anche aggiungere le tue nei commenti.
La mia soluzione è sicuramente applicabile a una gamma ristretta di problemi e forse troverai uno strumento più conveniente per disegnare diagrammi semplicemente codificandoli, come si suol dire "mostrami il tuo diagramma come codice"
- (9 tipi di editor online di grafici)
- E se ti piacciono i diagrammi super dettagliati e complessi, allora ammirerai sicuramente questo progetto:
Fonte: habr.com