Gdzie trzymacie dokumentacje ?

Odpowiedz Nowy wątek
2020-09-16 11:24

Rejestracja: 5 lat temu

Ostatnio: 4 dni temu

0

Cześć, gdzie trzymacie przykładowo opisy mikroserwisów, jakieś schematy przepływów w nich czy integracji ? W readme czy na czymś typu Confluence ?

Bo w sumie w obecnej pracy mamy trochę tak, a trochę tak bo każdemu róznie wygodniej. Ja np wolę czytać z readme, bo ciężko mi się czasem szuka w Confluence.

Pozostało 580 znaków

2020-09-16 11:27

Rejestracja: 1 rok temu

Ostatnio: 6 godzin temu

Lokalizacja: Silesia

4

Git jest jednym z najlepszych narzędzi do trzymania plików tekstowych jakie stworzono. Więc jeśli dokumentacja (zwłaszcza techniczna) jest w plikach tekstowych to w gicie.
Oczywiście problemem może być to że chcemy niektórym ludziom dać dostęp do dokumentacji i nie dawać dostępu do kodu. W rezultacie dokumentacja bardziej biznesowa ląduje w Confluence :(


Pozostało 580 znaków

2020-09-16 11:29

Rejestracja: 5 lat temu

Ostatnio: 4 dni temu

0

Też tak zawsze myślałem i też korzystałem w ten sposób.
Chciałem przepchać, żeby czysto techniczna dokumentacja była właśnie w git, ale powstały argumenty, że jak robimy diagramy w draw.io to git nie ma wsparcia, trzeba pobierać PNG albo dawać linki do draw.io, a Confluence ma wszystko.

Pozostało 580 znaków

2020-09-16 11:31

Rejestracja: 4 lata temu

Ostatnio: 1 tydzień temu

1

https://docusaurus.io/
Klepie się dokumentację w md, powstaje ładna stronka z tego. Ich strona jest zrobiona w tym-tym.

edytowany 1x, ostatnio: Tyvrel, 2020-09-16 11:34
A obsługuje cos takiego jak linki między stronami itp? - UglyMan 2020-09-16 11:40
Pomiędzy zewnętrznymi linkami - oczywiście, to jest tylko md. Pomiędzy poszczególnymi podstronami docusaurusa - oczywiście, bez tego byłoby bez sensu - Tyvrel 2020-09-16 11:42
Chodziło mi o linkowanie między dokumentami wewnętrznymi. Używasz tego na co dzień? Masz jakieś zastrzeżenia? - UglyMan 2020-09-16 11:44
Nie rozumiem o co chodzi z tymi dokumentami wewnętrznymi =( Zastrzeżeń nie mam żadnych, ale pragnę wspomnieć, że jestem tylko klepaczem CRUDów niegodnym nazwania się programistą i takowe cuda dokumentuję - Tyvrel 2020-09-16 11:47
Dzięki. pobadam temat. - UglyMan 2020-09-16 12:04

Pozostało 580 znaków

2020-09-16 11:33

Rejestracja: 2 lata temu

Ostatnio: 5 godzin temu

1

to może jeszcze napiszcie w jakich formatach plików. Często mnie wnerwia jakiś screenshot z ładnego schemaciki bazy danych gdzie brak typu pól

Pozostało 580 znaków

2020-09-16 11:40

Rejestracja: 4 lata temu

Ostatnio: 5 godzin temu

Lokalizacja: U krasnoludów - pod górą

9

Confluence to tzw. Secure Vault. Jak chcesz ukryć informację tak, żeby dostępna była tylko dla wtajemniczonych to wrzuć w Confluence. Normalnie nikt tam jej nie znajdzie.Wyszukiwarka Confluence to specjalny projekt naukowy - polegający na tym aby mając zalogowanego użytkownika i zadane słowo kluczowe znajdować dokumenty najmniej istotne dla tego szukającego. Taki antygoogle, kiedyś to będzie coś, ale myślę, że jako ludzkość jeszcze do tego nie dorosliśmy.

Generalnie staram się trzymać dokumentacje w projekcie - w tym samym repo.
Pliki głównie .md,
do API wrzucam pliki .http (scratch) (taki format intellij do trzymania wygodnych CURLi).

Obrazków raczej nie robię.


jeden i pół terabajta powinno wystarczyć każdemu
edytowany 1x, ostatnio: jarekr000000, 2020-09-16 11:41
Pokaż pozostałe 17 komentarzy
Jeszcze gorzej jak projekt jest agile, a wy musicie oddać ten diagram do zatwierdzenia w pierwszym miesiącu, zanim się jeszzcze dowiecie co macie robić Widziałem coś takiego. Jak się Tech Lead pieklił że to nie agile to mu manago powiedział że agile to oni są tylko wewnątrz firmy, a klient chce WaterFall. Potem się wydało że klient tych schematów nie chce tylko dyrektorzy. Zdaje się że ostatecznie Tech Lead tym rzucił - KamilAdam 2020-09-16 12:45
@Bambo: do takich wykresów ja używam PlantUML, GraphViz oraz Mermaid. W ten sposób masz możliwość składowania diagramów w postaci tekstowej. - hauleth 2020-09-16 14:31
Ja też bym używał. Ale chcą byśmy używali draw.io. - Bambo 2020-09-16 14:39
tak p.s drawi io ma chyba import dla mermaida ;p - Schadoow 2020-09-16 14:42
@jarekr000000: prawie się udławiłem ze śmiechu czytając ten post :D :D :D - mr_jaro 2020-09-16 16:49

Pozostało 580 znaków

2020-09-16 11:52

Rejestracja: 8 lat temu

Ostatnio: 16 godzin temu

1

@Bambo:
Patrzyłeś może na https://shd101wyy.github.io/markdown-preview-enhanced/#/ albo ascii doctor'a ?

Co do diagramów to asciidoctor jaki i markdown-review-enhanced obsługują trochę libek do rysowanie diagramów tu przykład: https://shd101wyy.github.io/m[...]n-preview-enhanced/#/diagrams
https://asciidoctor.org/docs/asciidoctor-diagram/

edytowany 1x, ostatnio: Schadoow, 2020-09-16 11:54

Pozostało 580 znaków

2020-09-16 12:05

Rejestracja: 4 miesiące temu

Ostatnio: 4 godziny temu

Lokalizacja: świat

5

Chwila to wy macie dokumentacje?


196 87 19

Pozostało 580 znaków

2020-09-16 12:13

Rejestracja: 6 lat temu

Ostatnio: 7 godzin temu

0

U mnie w pracy to wygląda tak:

  • Dokumentacje API trzymamy w folderze z frameworkiem, wraz z skryptem dzięki któremu można sobie wygenerować szybko doxygen'a
  • Dokumentacje specyfikacji trzymamy w autorskim systemie opierającym się na git, md oraz uml, który generuje dokument na żądanie w potrzebnym w danej chwili formacje (np. pdf albo html) oraz rewizji
  • Powyższe uzupełnia specjalny autorski system który zbiera powyższe rzeczy, do którego dodatkowo można dołożyć zewnętrzne dokumentacje, prezentacje, itd.
  • Do tego wiki oraz onenote w których znajduję się często howto albo porady
  • i to wszystko uzupełnia wyszukiwarka która sprawdza wszystkie rzeczy powyżej

Pozostało 580 znaków

2020-09-16 12:23

Rejestracja: 5 lat temu

Ostatnio: 6 godzin temu

1

Mieliśmy kiedyś potworzastego potwora generującego dokumentację wraz z aktualizacją screenshotów itd., gdzie bazowało to wszystko na LaTeX-u.

LaTeX do dokumentacji się nawet nadaje, chociaż to pewne nadużycie — lżejsze i łatwiejsze systemy będą zazwyczaj lepsze. Przy czym jak zaczynają się pojawiać wymagania z kosmosu, typu jakieś diagramy (których nikt nie ogląda), jakieś wzory matematyczne (których nikt nie czyta), rozrysowywane reakcje chemiczne z jakichś SMILES-ów, jakieś niewiadomoco, to może być tak, że będzie sensownym wyborem.

Wrzucasz wtedy do repo same pliki .tex — są tekstowe i dobrze się „dogadują” z systemami kontroli wersji — i w skryptach budujących dodajesz tworzenie z nich wynikowego pliku PDF.

edytowany 1x, ostatnio: Althorion, 2020-09-16 12:24
My mamy wymaganie na draw.io :| - Bambo 2020-09-16 12:30
A co złego w draw.io? Fajne narzędzie. - Pinek 2020-09-16 19:26

Pozostało 580 znaków

2020-09-16 15:31
Moderator

Rejestracja: 12 lat temu

Ostatnio: 4 godziny temu

Lokalizacja: Wrocław

0

Swagger, ale trudno powiedzieć, że to trzymanie, bo on się sam generuje przy każdym buildzie.


"HUMAN BEINGS MAKE LIFE SO INTERESTING. DO YOU KNOW, THAT IN A UNIVERSE SO FULL OF WONDERS, THEY HAVE MANAGED TO INVENT BOREDOM."

Pozostało 580 znaków

Odpowiedz

1 użytkowników online, w tym zalogowanych: 0, gości: 1, botów: 0