Dokumentacja techniczna \u2013 s\u0142owo, kt\u00f3re u wielu developer\u00f3w wywo\u0142uje westchnienie. W startupach i M\u015aP cz\u0119sto traktowana jest jak z\u0142o konieczne, odk\u0142adana na p\u00f3\u017aniej, a potem zapominana. Efekt? Nowi cz\u0142onkowie zespo\u0142u sp\u0119dzaj\u0105 dni na odkrywaniu, jak dzia\u0142a kod, a b\u0142\u0119dy powielaj\u0105 si\u0119, bo nikt nie spisa\u0142 decyzji architektonicznych. Z perspektywy biznesu to ukryty koszt, kt\u00f3ry mo\u017ce si\u0119ga\u0107 tysi\u0119cy z\u0142otych miesi\u0119cznie. Jako praktyk, kt\u00f3ry widzia\u0142 to od \u015brodka, poka\u017c\u0119 trzy najcz\u0119stsze b\u0142\u0119dy w podej\u015bciu do dokumentacji i konkretne rozwi\u0105zania.<\/p>\n
Wi\u0119kszo\u015b\u0107 firm zaczyna z dobrymi intencjami \u2013 tworzy wiki, readme, a nawet narz\u0119dzia jak Notion. Szybko jednak kod si\u0119 zmienia, a dokumentacja zostaje w tyle. Po p\u00f3\u0142 roku nikt nie ufa temu, co napisane, bo ka\u017cdy wie, \u017ce to nieaktualne. Z badania Stripe wynika, \u017ce deweloperzy trac\u0105 \u015brednio 17 godzin tygodniowo na \u201ezrozumienie kodu\u201d \u2013 cz\u0119sto przez w\u0142a\u015bnie nieaktualn\u0105 dokumentacj\u0119.<\/p>\n
Naprawa:<\/strong> Zamiast ogromnych dokument\u00f3w, postaw na dokumentacj\u0119 w kodzie \u2013 komentarze wyja\u015bniaj\u0105ce \u201edlaczego\u201d, nie \u201eco\u201d. U\u017cywaj narz\u0119dzi jak Swagger do API, kt\u00f3re generuj\u0105 dokumentacj\u0119 z kodu. Wprowad\u017a zasad\u0119: ka\u017cda zmiana w kodzie, kt\u00f3ra wp\u0142ywa na interfejs, musi aktualizowa\u0107 dokumentacj\u0119 w tym samym PR. Automatyzacja to tutaj klucz \u2013 je\u015bli dokumentacja nie jest automatycznie weryfikowana, umrze.<\/p>\n Cz\u0119sty widok: suche opisy funkcji, lista parametr\u00f3w, suchy kod. Taka dokumentacja jest bezu\u017cyteczna dla nowego cz\u0142onka zespo\u0142u, kt\u00f3ry chce zrozumie\u0107 kontekst biznesowy. Deweloperzy czytaj\u0105 dokumentacj\u0119, by znale\u017a\u0107 odpowied\u017a na pytanie: \u201ejak to dzia\u0142a i dlaczego tak, a nie inaczej?\u201d. Je\u015bli dokumentacja nie odpowiada na to pytanie, staje si\u0119 szumem.<\/p>\n Naprawa:<\/strong> Wprowad\u017a szablon dokumentacji, kt\u00f3ry wymaga: 1) kontekstu biznesowego (po co to?), 2) przyk\u0142ad\u00f3w u\u017cycia (jak to wywo\u0142a\u0107?), 3) decyzji architektonicznych (dlaczego tak?). Zadbaj, by dokumentacja by\u0142a pisana w formie narracji, nie listy. Przyk\u0142ad: zamiast \u201efunkcja getUser(id) zwraca obiekt user\u201d napisz \u201efunkcja getUser(id) pozwala pobra\u0107 dane u\u017cytkownika do wy\u015bwietlenia w profilu. U\u017cywamy jej na stronie ustawie\u0144. Dlaczego oddzielamy to od API zam\u00f3wie\u0144? Bo w przysz\u0142o\u015bci planujemy cache\u2019owa\u0107 profil\u201d.<\/p>\n W wielu zespo\u0142ach dokumentacja spada na barki jednej osoby \u2013 np. tech leada lub nowego sta\u017cysty. Reszta zespo\u0142u czuje si\u0119 zwolniona z obowi\u0105zku. To prosta droga do powstania luki: nikt nie wie wszystkiego, a kluczowa wiedza pozostaje w g\u0142owach cz\u0142onk\u00f3w zespo\u0142u (ang. bus factor).<\/p>\n Naprawa:<\/strong> Zr\u00f3b dokumentacj\u0119 cz\u0119\u015bci\u0105 Definition of Done. Ka\u017cda funkcjonalno\u015b\u0107 jest gotowa dopiero, gdy ma aktualn\u0105 dokumentacj\u0119. Rotuj odpowiedzialno\u015b\u0107 \u2013 co sprint inna osoba przegl\u0105da i aktualizuje dokumentacj\u0119. U\u017cywaj narz\u0119dzi jak ADRs (Architecture Decision Records), kt\u00f3re s\u0105 kr\u00f3tkimi wpisami o podj\u0119tych decyzjach \u2013 ka\u017cdy mo\u017ce je tworzy\u0107 i przegl\u0105da\u0107.<\/p>\n Dokumentacja nie musi by\u0107 ci\u0119\u017carem. Mo\u017ce by\u0107 narz\u0119dziem oszcz\u0119dzaj\u0105cym czas i pieni\u0105dze, je\u015bli podejdzie si\u0119 do niej systemowo. Pami\u0119taj: dokumentacja to nie archiwum, to instrukcja obs\u0142ugi dla przysz\u0142ych deweloper\u00f3w \u2013 w tym dla Ciebie za p\u00f3\u0142 roku. Zacznij od ma\u0142ych krok\u00f3w: wybierz jeden b\u0142\u0105d z powy\u017cszych i wdr\u00f3\u017c poprawk\u0119 w nast\u0119pnym sprincie. Efekty zobaczysz szybciej, ni\u017c my\u015blisz.<\/p>\n","protected":false},"excerpt":{"rendered":" Dlaczego Tw\u00f3j zesp\u00f3\u0142 developer\u00f3w ignoruje dokumentacj\u0119? 3 b\u0142\u0119dy i naprawa Dokumentacja techniczna \u2013 s\u0142owo, kt\u00f3re u wielu developer\u00f3w wywo\u0142uje westchnienie. W startupach i M\u015aP cz\u0119sto traktowana jest jak z\u0142o konieczne, odk\u0142adana na p\u00f3\u017aniej, a potem zapominana. Efekt? Nowi cz\u0142onkowie zespo\u0142u sp\u0119dzaj\u0105 dni na odkrywaniu, jak dzia\u0142a kod, a b\u0142\u0119dy powielaj\u0105 si\u0119, bo nikt nie spisa\u0142<\/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":[135,179,113,1071],"class_list":["post-2867","post","type-post","status-publish","format-standard","hentry","category-warto-wiedziec","tag-dokumentacja-techniczna","tag-efektywnosc-ai","tag-jakosc-kodu","tag-zespol-developerski"],"_links":{"self":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts\/2867","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=2867"}],"version-history":[{"count":0,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts\/2867\/revisions"}],"wp:attachment":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/media?parent=2867"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/categories?post=2867"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/tags?post=2867"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}B\u0142\u0105d nr 2: Dokumentacja jest pisana dla maszyn, nie dla ludzi<\/h3>\n
B\u0142\u0105d nr 3: Dokumentacja to odpowiedzialno\u015b\u0107 \u201ekogo\u015b innego\u201d<\/h3>\n
Podsumowanie<\/h3>\n