Gdzie trzymacie dokumentacje ?

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.

5

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 :(

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.

1

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

2

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

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ę.

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/markdown-preview-enhanced/#/diagrams
https://asciidoctor.org/docs/asciidoctor-diagram/

5

Chwila to wy macie dokumentacje?

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
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.

0

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

0
somekind napisał(a):

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

Tylko jeśli generujesz go z adnotacji. Niektórzy klepią ręcznie swagger.yaml XD

4

Nie ma dokumentacji, wiedza jest w ludziach.

1
Marcin Marcin napisał(a):

Nie ma dokumentacji, wiedza jest w ludziach.

Dokładnie. Porządny projekt odznacza się 2 rzeczami: brak dokumentacji (bo wiedza jest w ludziach) oraz brak testów (bo aplikacja jest tak dobra, że i tak nie byłoby błędów)

4

Jaką dokumentację? ¯_(ツ)_/¯

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