W ciągu ostatnich kilku lat bardziej zaangażowałem się w dokumentację. Napisanie tekstu wyjaśniającego, jak działa ten lub inny system, jest ogólnie dość proste. Narysowanie diagramu, który wyświetli wszystkie kluczowe obiekty i połączenia między tymi obiektami, jest również dość łatwe.
Jednak najbardziej problematycznym aspektem jest aktualizowanie tej dokumentacji. I tekst byłby w porządku, ale diagramy... Ponieważ... cała dokumentacja jest dostępna online, tj. w formacie html, wówczas do tekstu dołączone są obrazy gif/jpeg/png, które w rzeczywistości przedstawiają diagramy. Diagramy są rysowane w różnych programach, takich jak Visio lub usługi online a la Draw.io. Następnie eksportujesz diagram do formatu graficznego i dołączasz go do HTML. To proste.
W czym jest problem
Schematy są zazwyczaj proste. Dokładniej, niezbyt skomplikowane. Tak, liczba obiektów to kilkanaście lub dwa, liczba połączeń jest w przybliżeniu taka sama. Plus podpisy, jakieś oznaczenia. Proste schematy można opisać słowami, ale zbyt skomplikowane, hm… (c) „oni nie zrozumieją, proszę pana”. Schematów jest wiele, zmiany należy wprowadzać w nich okresowo, epizodycznie, tj. stale, ponieważ śledzą rozwój naszych produktów.
Możesz osadzić kod HTML usługi. Próbowałeś tego?
Tak, oczywiście. Podobają mi się na przykład grafiki z gliffy.com. Aby jednak wprowadzić zmiany, musisz udać się do usługi innej firmy i tam dokonać edycji. Trudniej jest także delegować poprawki współpracownikowi.
Co robić?
Ostatnio w rekomendacjach natknąłem się na repozytorium na Githubie . Schemat jako kod. Te. opisujemy obwód, którego potrzebujemy w js. Piszemy ten plik js bezpośrednio w tym samym kodzie HTML, w którym znajduje się inny tekst dokumentacji.
Nawiasem mówiąc, dokumentację piszę nie całkowicie w HTML. Zazwyczaj dokumentacja to zestaw plików z tekstem przeceny, który następnie jest przekształcany w pełnoprawną witrynę z dokumentacją przez jakiś silnik, na przykład Wintersmith. Albo system wiki.
Okazuje się to bardzo wygodne: napisaliśmy tekst, następnie otwiera się znacznik skryptu i opisany jest w nim kod JS schematu.
Co się znowu dzieje?
Podobało mi się to repozytorium, ale nie jest to jedyny przykład rysowania diagramu przy użyciu kodu lub reprezentacji tekstowej. (Na końcu artykułu będą linki do projektów i artykułów, które wyszukałem w Google na diagramie tematycznym jako kod.)
I nie tylko ja edytuję dokumentację. Czasami współpracownicy również wnoszą swój wkład - popraw słowo, zmień opis, wstaw nowe zdjęcia.
Dlatego chciałbym zobaczyć diagram w czytelnej, zrozumiałej formie tekstowej, która nie wymagałaby długiej krzywej uczenia się. W niektórych miejscach możesz nawet po prostu skopiować i wkleić, aby przyspieszyć dodanie nowego obwodu.
A inny kolega zauważył, że kod jest oczywiście dobry, ale jeśli zastosujesz strukturę, wszystko może być bardzo rygorystyczne i wyraziste.
Dlatego próbowałem wyobrazić sobie diagram jako zbiór kilku małych tablic opisujących węzły, połączenia, grupy węzłów, a także lokalizację węzłów. Okazało się moim skromnym zdaniem całkiem wygodne, choć oczywiście smak i kolor...
Jak wygląda wykres w tablicy?
- Każdy węzeł jest opisany identyfikatorem, który jednoznacznie identyfikuje węzeł.
- Możesz także dodać ikonę do węzła i dodać napis.
- Można określić relację pomiędzy dwoma węzłami.
- Do komunikacji na schemacie można ustawić kolor i napis.
- Kierunek komunikacji definiuje się jako od źródła do celu. Źródło i cel są oznaczone identyfikatorami węzłów.
- Do grupy można dodać jeden lub więcej węzłów.
- Relację można również określić zarówno z grupy, jak i do grupy.
Korzystając z tych prostych zasad, otrzymujemy następujący schemat. Tylko? Całkiem.
Opisuje to poniższy kod js. Najważniejsze jest tutaj obiekt elementów. W którym wskazane są węzły - węzły, krawędzie - połączenia.
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);
Oczywiście nie sam wymyśliłem rysunek obwodu, ale skorzystałem z biblioteki to bardzo potężne narzędzie do wizualizacji. Wykorzystuję tylko ułamek możliwości mojego rozwiązania.
OK, to jest prosty przykład. Czy to może być bardziej skomplikowane?
Tak proszę. Aby wskazać pozycje, używamy pozycji, aby wskazać grupy, wskazujemy listę grup w grupach, a same elementy mają atrybut grupowy.
A to jest kod:
<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>
Z jednej strony taki schemat to prawie kilka ekranów kodu na laptopie, z drugiej strony struktura a la json pozwala na uzupełnienie wszystkich danych analogicznie, szybko i można kopiować-wklejać.
Dlaczego pozycje są umieszczane oddzielnie od węzłów?
Jest wygodniej. Najpierw określamy węzły. Następnie możemy określić kilka grup i wskazać je w węzłach. Następnie wyznaczamy połączenia. I dopiero wtedy, gdy już istnieją główne obiekty i połączenia między nimi, zajmujemy się lokalizacją tych obiektów na schemacie. Lub odwrotnie.
Czy jest to możliwe bez stanowisk?
Jest to możliwe bez stanowisk. Ale będzie trochę pognieciony, możesz zobaczyć tę opcję w przykładach. Wynika to z faktu, że istnieje algorytm lokalizacji węzłów dla cytoscape , który uwzględnia również obecność grup. Określenie pozycji sprawia, że diagram jest bardziej sterowalny, ale na etapie pierwszego szkicu diagramu jest to możliwe bez pozycji.
Pozycje można również określić w stylu pancernika. Te. jeden węzeł znajduje się w a1, a drugi w d5. Szczególnie pomaga to, że cytoscape sprawia, że obiekty na płótnie są ruchome, tj. możemy je przenosić, przeglądać różne opcje układu, a następnie poprawiać ułożenie elementów, które nam się podobają w kodzie.
Generalnie jest to zrozumiałe. Możesz też spróbować?
Oczywiście, żeby szybko stworzyć obwody, zrobiłem sobie mały , który sam aktualizuje schemat i przechowuje najnowszą wersję w przeglądarce (w localStorage).
Próbowałeś tego? Możesz teraz dodać go do swojej strony.
Potem znowu:
1. Podłączenie skryptu
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Dodaj kod do 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. edytujemy kod do potrzebnego diagramu (myślę, że to łatwiejsze niż narysowanie sowy :)
Więcej szczegółów pod adresem na githubie.
Wynik?
Osiągnąłem swoje cele - dodanie diagramów inline do dokumentacji, format jest dość prosty i zrozumiały. Nie nadaje się do super obwodów, ale do małych obwodów wyjaśniających strukturę połączeń jest absolutnie w porządku. Zawsze możesz szybko coś poprawić i zmienić z biegiem czasu. Tak, a koledzy mogą sami poprawić coś w stacji dokującej, przynajmniej napisy do obiektów, bez specjalnego przeszkolenia))
Co można poprawić?
Opcji jest tutaj oczywiście wiele. Dodaj dodatkowe ikony (wszystkie istniejące zostaną dodane bezpośrednio do skryptu). Wybierz bardziej wyrazisty zestaw ikon. Umożliwia określenie stylu linii połączenia. Dodaj obraz tła.
Co myślisz?
Mam już kilka pomysłów na realizację w numerach, możecie też dodawać swoje w komentarzach.
Moje rozwiązanie z pewnością ma zastosowanie w wąskim zakresie problemów i być może znajdziesz wygodniejsze narzędzie do rysowania diagramów, po prostu je kodując - jak to się mówi: „pokaż mi swój diagram jako kod”
- (edytor online 9 typów wykresów)
- A jeśli lubisz bardzo szczegółowe i złożone diagramy, na pewno będziesz podziwiać ten projekt:
Źródło: www.habr.com