Wi\u0119kszo\u015b\u0107 programist\u00f3w nienawidzi pisa\u0107 dokumentacji. Ale rzadko kto zadaje sobie pytanie: dlaczego? Zamiast obwinia\u0107 zesp\u00f3\u0142, przyjrzyjmy si\u0119 trzem b\u0142\u0119dom systemowym, kt\u00f3re sprawiaj\u0105, \u017ce dokumentacja staje si\u0119 bezu\u017cytecznym balastem. Ignorowanie dokumentacji to cz\u0119sto objaw z\u0142ego procesu, a nie lenistwa.<\/p>\n
Pierwszy b\u0142\u0105d to traktowanie dokumentacji jak obowi\u0105zku do odhaczenia \u2013 formalno\u015bci, kt\u00f3ra nie przynosi realnej warto\u015bci. W wielu firmach dokumentacja jest pisana na ko\u0144cu projektu, pod presj\u0105, cz\u0119sto przez osoby, kt\u00f3re ju\u017c dawno my\u015bl\u0105 o kolejnym zadaniu. Efektem jest sucha lista funkcji API albo opis architektury, kt\u00f3rego nikt nie przeczyta.<\/p>\n
Przyk\u0142ad z \u017cycia:<\/strong> Rozwi\u0105zanie: dokumentacja powinna by\u0107 tworzona iteracyjnie, jak kod \u2013 z przegl\u0105dami i aktualizacjami. U\u017cywaj narz\u0119dzi, kt\u00f3re generuj\u0105 j\u0105 z kodu (OpenAPI, JSDoc) i uzupe\u0142niaj opisami tam, gdzie automatyka nie wystarczy.<\/p>\n Drugi b\u0142\u0105d to brak w\u0142a\u015bciciela dokumentacji. Kiedy ka\u017cdy mo\u017ce edytowa\u0107, ale nikt nie czuje si\u0119 odpowiedzialny, dokumentacja szybko si\u0119 dezaktualizuje. Programi\u015bci wiedz\u0105, \u017ce dokumentacja jest nie\u015bwie\u017ca, wi\u0119c jej nie ufaj\u0105 \u2013 wol\u0105 czyta\u0107 kod lub zagl\u0105da\u0107 starszym kolegom przez rami\u0119.<\/p>\n Statystyka z praktyki:<\/strong> Rozwi\u0105zanie: wyznacz osob\u0119 odpowiedzialn\u0105 za dokumentacj\u0119 w ramach ka\u017cdego projektu (rola mo\u017ce rotowa\u0107). Wpisz aktualizacj\u0119 dokumentacji jako zadanie w sprint review. Im cz\u0119\u015bciej dokumentacja jest u\u017cywana (np. w onboarding), tym cz\u0119\u015bciej b\u0119dzie poprawiana.<\/p>\n Trzeci b\u0142\u0105d to u\u017cywanie narz\u0119dzi, kt\u00f3re s\u0105 dla programist\u00f3w uci\u0105\u017cliwe. Pisanie dokumentu w Wordzie, a nawet w Confluence bez integracji z kodem jest skazane na pora\u017ck\u0119. Programi\u015bci chc\u0105 mie\u0107 dokumentacj\u0119 blisko kodu \u2013 w repozytorium, w formacie markdown, z mo\u017cliwo\u015bci\u0105 przegl\u0105dania i komentowania przez pull requesty.<\/p>\n Przyk\u0142ad:<\/strong> Rozwi\u0105zanie: wybierz narz\u0119dzie, kt\u00f3re integruje si\u0119 z procesem developmentu \u2013 Git, CI\/CD, generowanie dokumentacji z kodu. Dla API \u2013 OpenAPI, dla architektury \u2013 C4 model. Minimalizuj r\u0119czne pisanie.<\/p>\n Zamiast zmusza\u0107 zesp\u00f3\u0142 do pisania dokumentacji pod gro\u017ab\u0105, postaw na system, kt\u00f3ry to u\u0142atwia. Traktuj dokumentacj\u0119 jak produkt \u2013 musi by\u0107 u\u017cyteczna, aktualna i \u0142atwa w utrzymaniu. W JurskiTech wiemy, \u017ce dobra dokumentacja to oszcz\u0119dno\u015b\u0107 czasu i pieni\u0119dzy w skali ca\u0142ej organizacji. Przyjrzyj si\u0119 swoim procesom \u2013 by\u0107 mo\u017ce to nie zesp\u00f3\u0142 jest problemem, tylko system, w kt\u00f3rym pracuje.<\/p>\n","protected":false},"excerpt":{"rendered":" Dlaczego Tw\u00f3j zesp\u00f3\u0142 programistyczny ignoruje dokumentacj\u0119? 3 b\u0142\u0119dy Wi\u0119kszo\u015b\u0107 programist\u00f3w nienawidzi pisa\u0107 dokumentacji. Ale rzadko kto zadaje sobie pytanie: dlaczego? Zamiast obwinia\u0107 zesp\u00f3\u0142, przyjrzyjmy si\u0119 trzem b\u0142\u0119dom systemowym, kt\u00f3re sprawiaj\u0105, \u017ce dokumentacja staje si\u0119 bezu\u017cytecznym balastem. Ignorowanie dokumentacji to cz\u0119sto objaw z\u0142ego procesu, a nie lenistwa. 1. Dokumentacja jako karanie zamiast narz\u0119dzia Pierwszy b\u0142\u0105d to<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[502,135,1044,939],"class_list":["post-2783","post","type-post","status-publish","format-standard","hentry","category-warto-wiedziec","tag-dokumentacja-api","tag-dokumentacja-techniczna","tag-efektywnosc-programistow","tag-zarzadzanie-zespolem-it"],"_links":{"self":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts\/2783","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/comments?post=2783"}],"version-history":[{"count":0,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts\/2783\/revisions"}],"wp:attachment":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/media?parent=2783"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/categories?post=2783"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/tags?post=2783"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
\nPracowa\u0142em z zespo\u0142em, kt\u00f3ry utrzymywa\u0142 wewn\u0119trzn\u0105 bibliotek\u0119. Dokumentacja by\u0142a \u2013 dwa pliki markdown z list\u0105 endpoint\u00f3w, bez przyk\u0142ad\u00f3w, bez opisu b\u0142\u0119d\u00f3w. Nowy developer traci\u0142 dwa dni na zrozumienie dzia\u0142ania. Po wprowadzeniu dokumentacji z przyk\u0142adami i sekcj\u0105 \u201etypowe problemy\u201d czas wdro\u017cenia skr\u00f3ci\u0142 si\u0119 do kilku godzin.<\/p>\n2. Brak odpowiedzialno\u015bci i aktualizacji<\/h2>\n
\nW jednym z projekt\u00f3w audytowa\u0142em repozytorium i okaza\u0142o si\u0119, \u017ce 70% dokumentacji opisuje ju\u017c nieistniej\u0105ce funkcjonalno\u015bci. Nikt nie mia\u0142 czasu na aktualizacj\u0119, bo nie by\u0142o za to odpowiedzialnej osoby.<\/p>\n3. Z\u0142e narz\u0119dzia i format<\/h2>\n
\nFirma, kt\u00f3ra przesz\u0142a z Confluence na strony generowane z dokumentacji w repozytorium (MkDocs, GitBook), odnotowa\u0142a 3-krotny wzrost liczby commit\u00f3w do dokumentacji. Po prostu usuni\u0119to barier\u0119 wej\u015bcia.<\/p>\nPodsumowanie<\/h2>\n