Zasady dokumentacji 1.2.0¶
Streszczenie¶
Dokumentacja Logintegry to strony Markdown w repozytoriach, budowane przez Zensical w jedną stronę. Każda strona ma jeden cel, jednego czytelnika i datę, od której opisuje stan. Tekst przechodzi automatyczny linting (TODO). Zmiany zgłaszamy przez YouTrack, a nieaktualne strony usuwamy albo przepisujemy. Dokumentacja w kodzie, czyli Javadoc, Groovydoc i KDoc, należy do zwykłej pracy programisty.
Wprowadzenie¶
Dokumentacja rozjeżdża się z rzeczywistością po cichu. Nikt nie wie, która strona jest aktualna, gdzie szukać odpowiedzi ani jak zgłosić błąd. Te zasady ustalają, gdzie dokumentacja mieszka, jak wygląda strona, jak piszemy i jak strona się zmienia. Obejmują też dokumentację w kodzie.
Zasady są wersjonowane jak oprogramowanie. Numer wersji w tytule mówi, czy zmiana zasad wymaga poprawiania istniejących stron. Szczegóły opisuje sekcja "O dokumencie".
Specyfikacja zasad dokumentacji¶
Dokumentacja inspirowana https://semver.org/. Słowa MUSI, NIE MOŻE, POWINIEN, NIE POWINIEN i MOŻE oparte o znaczenie z RFC 2119. MUSI i NIE MOŻE to wymóg bez wyjątków. POWINIEN i NIE POWINIEN dopuszczają wyjątek, ale wyjątek wymaga uzasadnienia w PR. MOŻE oznacza swobodny wybór.
Miejsce¶
- Dokumentacja projektu MUSI leżeć w katalogu
docs/repozytorium, którego dotyczy. Repozytorium MUSI miećzensical.tomlalbomkdocs.yml, żebyscripts/ws docs buildzbudował jego stronę. - Dokumentacja wspólna dla wielu repozytoriów MUSI leżeć w
docs/repozytoriumlogintegra-workspace. - Każda strona MUSI mieć wpis w
navkonfiguracji swojej witryny. Strona spozanavjest niewidoczna dla czytelnika. - Nowa witryna repozytorium MUSI dostać link na stronie startowej, czyli w
docs/index.mdworkspace'u. - Dokumentacja generowana z kodu, np. OpenAPI, MUSI powstawać z kodu przez wpis w
docs.toml. NIE MOŻNA jej przepisywać ręcznie.
Budowa strony¶
- Strona MUSI mieć dokładnie jeden nagłówek pierwszego poziomu i jest nim tytuł strony.
- Pierwszy akapit MUSI mówić, czego strona dotyczy i dla kogo jest. Czytelnik po jednym akapicie wie, czy jest we właściwym miejscu.
- Strona z propozycją albo planem MUSI mieć pod tytułem znacznik
[DRAFT]albo[PLAN]i datę, np.[PLAN] Stan na 2026-09-25.Strona bez znacznika opisuje stan obowiązujący. - Plan POWINIEN mieć sekcje w tej kolejności: problem, zasada rozwiązania, plan wdrożenia, ryzyka, otwarte pytania. Każdy etap planu POWINIEN kończyć się zdaniem "Gotowe, gdy …".
- FAQ MUSI mieć pytania jako nagłówki drugiego poziomu, numerowane i zakończone znakiem zapytania.
- Decyzja zapisana na stronie MUSI mieć datę i opis, kto albo co ją podjęło.
- Strona POWINNA mieć co najwyżej około 2000 słów. Dłuższy materiał POWINIEN zostać podzielony na strony połączone linkami.
Język i styl¶
- Dokumentacja MUSI być po polsku. Nazwy z kodu, polecenia, ścieżki i komunikaty błędów zostają w oryginale.
- Tekst MUSI spełniać zasady stylu z tabeli poniżej (https://github.com/NullVoxPopuli/nollm).
Większość z nich sprawdza
scripts/ws docs lint(TODO). Cytowane przykłady złego stylu MOŻNA wyłączyć z lintu komentarzami<!-- doclint: off -->i<!-- doclint: on -->. - W źródle Markdown każde zdanie MUSI stać w osobnej linii. Linia NIE MOŻE kończyć się w połowie frazy.
- Pary etykieta–wartość POWINNY trafiać do tabeli, a nie do listy z pogrubionym początkiem.
- Polecenia, ścieżki, nazwy plików, zmiennych i hostów MUSZĄ być w
kodzie. Blok kodu MUSI mieć podany język, np.bash,hclalboyaml. - Polecenie w bloku kodu MUSI dać się skopiować i uruchomić bez zmian albo zawierać jawny symbol zastępczy w postaci
<nazwa>.
| Zasada | Czego unikamy |
|---|---|
| bez półpauzy (em dash) | znaku — w tekście |
| bez pogrubionych etykiet na liście | - **Etykieta:** tekst |
| bez wtrąceń w nawiasach | dopowiedzeń w środku zdania |
| bez waty słownej | "po prostu", "naprawdę", "kluczowy", "kompleksowy", "solidny" |
| bez sztucznych kontrastów | "nie tylko X, ale Y", "to nie X, to Y" |
| bez pytań retorycznych | "Dlaczego? Bo…", "Efekt?" |
| bez dramatyzowania | "wywala się", "wybucha", "sypie się" |
| bez treści, która szybko się zestarzeje | "na razie", "już nie", "dotychczas", "wcześniej" |
| krótkie zdania | więcej niż 30 słów w zdaniu |
| krótkie akapity | więcej niż 120 słów albo 7 zdań w akapicie |
| zmienny rytm | kilka zdań albo akapitów o tej samej długości pod rząd |
Diagramy¶
- Diagram MUSI być w Mermaid, w bloku kodu
mermaid. Obrazy diagramów NIE MOGĄ zastępować źródła Mermaid. - Kolory w diagramie POWINNY być ustawione tylko na obramowaniach węzłów. Wypełnienie i tekst zostają z motywu, więc diagram działa w trybie jasnym i ciemnym.
- Diagram MUSI mieć legendę, jeśli kolor albo styl linii niesie znaczenie.
Linki¶
- Linki między stronami tej samej witryny MUSZĄ być względne i wskazywać plik
.md. - Link do sekcji MUSI używać kotwicy, którą generuje Zensical.
Poprawność kotwic sprawdza
scripts/ws docs build. - Link do innego repozytorium POWINIEN prowadzić do jego witryny na stronie workspace'u, a nie do Bitbucketa.
Sekrety i dane¶
- Strona NIE MOŻE zawierać haseł, tokenów, kluczy prywatnych ani innych sekretów.
W ich miejscu stoi
<VAULT>albo nazwa wpisu w Vault. - Strona MOŻE podawać adresy IP i nazwy hostów wewnętrznej infrastruktury. Witryna jest dostępna tylko dla zespołu, więc to dopuszczalne.
- Strona NIE MOŻE zawierać danych osobowych klientów ani danych z produkcyjnych baz.
Linting (TODO)¶
- Zmiana dokumentacji MUSI przejść przez PR, jak zmiana kodu.
scripts/ws docs lintMUSI kończyć się wynikiem "0 findings" dla repozytoriów objętych lintem.scripts/ws docs buildMUSI kończyć się bez błędów, a strona zmienionej witryny z wynikiem "No issues found".- Autor zmiany z diagramem POWINIEN obejrzeć wyrenderowaną stronę przed wysłaniem PR.
Cykl życia strony¶
- Prośby o nową stronę, zmianę albo wygaszenie strony MUSZĄ trafiać do YouTrack. Służą do tego przyciski pod każdą stroną, które otwierają wypełniony szkic zgłoszenia.
- Strona nieaktualna MUSI zostać przepisana albo usunięta. NIE MOŻNA zostawiać przekreśleń ani akapitów "Aktualizacja z dnia …" obok starej treści.
- Usunięcie strony MUSI usunąć też jej wpis w
navi linki do niej. - Zmiana w kodzie, która zmienia opisane zachowanie, POWINNA zmieniać dokumentację w tym samym PR.
Dokumentacja w kodzie¶
Javadoc, Groovydoc i KDoc są częścią zwykłej pracy programisty, tak jak testy i nazwy zmiennych. Piszemy je przy okazji zmiany kodu, gdy to możliwe, i zawsze, gdy to konieczne. Konieczne jest to w przypadkach z zasady 36.
-
Komentarz dokumentacyjny MUSI mieć każda z tych części kodu:
- publiczna metoda serwisu albo klasy używanej przez inne moduły
- metoda z efektem ubocznym, którego nie widać w nazwie
- obejście błędu albo ograniczenia z zewnętrznego systemu
- klasa lub metoda oznaczona
@Deprecated
-
Kod, którego dotyczy PR, POWINIEN dostać komentarz dokumentacyjny, jeśli autor musiał go czytać dłużej niż chwilę, żeby go zrozumieć.
- Komentarz NIE POWINIEN opisywać oczywistych rzeczy, np. getterów, setterów i metod, których nazwa mówi wszystko.
- Komentarz MUSI opisywać kontrakt: co metoda robi, co przyjmuje, co zwraca i kiedy rzuca wyjątek. Opis kroków implementacji NIE POWINIEN trafiać do komentarza dokumentacyjnego.
- Komentarz MUSI wymienić efekty uboczne, np. zapis do bazy, wysłanie wiadomości do RabbitMQ albo wywołanie zewnętrznego API.
- Komentarz POWINIEN wyjaśniać, dlaczego kod działa w dany sposób, jeśli powód nie wynika z kodu.
Powód POWINIEN mieć numer zgłoszenia w nawiasach kwadratowych, np.
[A-14086]. @deprecatedMUSI wskazywać zamiennik przez{@link}albo@seei numer zgłoszenia, które usunie stary kod.TODOMUSI mieć numer zgłoszenia w postaci// TODO A-12345: opis.TODObez zgłoszenia NIE MOŻE trafić do mastera.- Komentarz MUSI być w języku, którego używa reszta pliku. Nowy plik POWINIEN mieć komentarze po angielsku.
- Komentarz MUSI spełniać zasady stylu z zasady 14. Lint nie sprawdza kodu, więc zasady stylu w komentarzach sprawdza recenzent PR.
- Endpoint REST MUSI być opisany adnotacjami OpenAPI, np.
@Operationi@ApiResponse, a nie tylko komentarzem. Komentarz dokumentacyjny kontrolera MOŻE opisywać szczegóły, które nie trafiają do API.
README i CONTRIBUTING¶
- Repozytorium z kodem MUSI mieć w korzeniu plik
README.mdzgodny z szablonem README. README MUSI opisywać stos, wymagania, uruchomienie, konfigurację oraz testy i budowanie. - Repozytorium z kodem MUSI mieć w korzeniu plik
CONTRIBUTING.mdzgodny z szablonem CONTRIBUTING.CONTRIBUTING.mdNIE MOŻE powtarzać procesu pracy, tylko do niego odsyła i opisuje wyjątki. - Polecenia w
README.mdMUSZĄ dawać się wykonać na czystym klonie repozytorium. - README POWINNO być krótkie.
Opisy dłuższe niż jedna sekcja POWINNY trafić do
docs/repozytorium, a w README zostaje link. - Wymagania z zasad 47 i 48 obowiązują nowe repozytoria od razu, a istniejące przy pierwszej zmianie ich README.
Dlaczego te zasady¶
Czytelnik dokumentacji zwykle czegoś szuka w trakcie pracy. Krótkie zdania, tabele i jeden cel strony skracają to szukanie.
Zasady stylu sprawdza narzędzie, więc przegląd PR może skupić się na treści. Jedna struktura planów i FAQ sprawia, że każdą stronę czyta się tak samo.
Wersjonowanie zasad mówi autorom, kiedy muszą poprawić stare strony.
FAQ¶
Co zrobić, gdy zasada nie pasuje do strony?¶
Zasadę POWINIEN albo NIE POWINIEN można pominąć z uzasadnieniem w opisie PR. Zasadę MUSI zmienia się tylko przez nową wersję tego dokumentu.
Czy lint obejmuje wszystkie repozytoria?¶
Nie.
scripts/ws docs lint domyślnie sprawdza logintegra-ansible.
Inne pliki można podać wprost: scripts/ws docs lint <ścieżka>.
Czy trzeba poprawiać stare strony po zmianie zasad?¶
Tylko po zmianie wersji głównej, np. z 1.x.x na 2.0.0. Zmiany wersji pobocznej i poprawki dotyczą nowych i edytowanych stron.
Czy trzeba dopisać dokumentację do całej klasy, którą zmieniam?¶
Nie. Zasada 36 dotyczy kodu, który dodajesz albo zmieniasz. Resztę klasy dokumentujesz według zasady 37, jeśli jej zrozumienie zajęło ci czas.
Jak wygląda dobry komentarz dokumentacyjny?¶
/**
* Przedłuża ważność tokenu autoryzacyjnego, żeby nie usunął go {@link logintegra.RemoveStaleTokensJob} [A-14086].
*
* @param token token zalogowanego użytkownika
* @return token z nową datą w polu {@code refreshed}
* @throws IllegalStateException gdy token jest już unieważniony
*/
Skąd wziąć szablon strony?¶
Najbliższym wzorem jest istniejąca strona tego samego typu. Plan: TeamCity bez commitu na maszynę. FAQ: FAQ: jak pracujemy.
O dokumencie¶
Wersja tego dokumentu ma postać MAJOR.MINOR.PATCH, jak w Semantic Versioning.
| Zmiana | Przykład | Wersja |
|---|---|---|
| zasada usunięta albo zaostrzona tak, że istniejące strony przestają ją spełniać | POWINIEN zmienia się w MUSI | MAJOR |
| nowa zasada, która nie narusza istniejących stron | nowa sekcja o diagramach | MINOR |
| poprawka sformułowania bez zmiany znaczenia | literówka, lepszy przykład | PATCH |
Każda zmiana wersji MUSI mieć wpis w historii poniżej.
| Wersja | Data | Zmiany |
|---|---|---|
| 1.2.0 | 2026-10-02 | README i CONTRIBUTING: zasady 47-51, szablony i strona procesu pracy |
| 1.1.0 | 2026-09-30 | dokumentacja w kodzie: zasady 36-46 |
| 1.0.0 | 2026-09-29 | pierwsza wersja |
Ostatnia zmiana: 2026-10-06 · Dariusz Bakowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e