Jakiej dokumentacji wymagać od dostawcy oprogramowania

Masz kod. Ale czy masz wiedzę, jak ten kod działa oraz jak go modyfikować i utrzymywać? Dostawca zna podjęte decyzje i wie „dlaczego tak, a nie inaczej”. Ty zazwyczaj dostajesz repozytorium i martwą dokumentację, której nikt nie otwiera. A gdy dostawca znika, zostajesz z kodem bez kontekstu. Poniżej pokazujemy, jakiej dokumentacji wymagać od zewnętrznego dostawcy oprogramowania, żeby naprawdę chroniła produkt: co ma zawierać, w jakiej formie ma żyć i dlaczego jest szczególnie ważna przy pracy z AI.

Co się dzieje, gdy wiedza o projekcie IT zostaje w głowach programistów dostawcy

Problem słabej dokumentacji albo jej braku nie pojawia się w dniu zakończenia umowy. Zwykle ciągnie się od pierwszych decyzji, których nikt nie spisuje tak, żebyś Ty i Twój zespół mogli do nich wrócić później.

Nowa osoba w projekcie pyta o przebieg procesu. Odpowiedź brzmi: „zapytaj Marka”. Marek jest na urlopie. Albo już nie pracuje u dostawcy. Albo nadal pracuje, ale wiedza została w wątku na Slacku sprzed roku. To ten sam mechanizm, który w branży nazywamy bus factorem: im mniej osób zna krytyczny kontekst, tym większe ryzyko, że po ich odejściu rozwój produktu się zatrzyma. Chyba że dostawca tę wiedzę odpowiednio udokumentuje.

Najwyraźniej widać to przy przejmowaniu projektów. Nowy zespół dostaje kod i musi odtwarzać założenia z commitów, ticketów i domysłów. Ale słaba dokumentacja utrudnia też codzienną pracę. Onboarding trwa o wiele dłużej, niż powinien. Know-how znika wraz z rotacją pracowników. A gdy do kodu wchodzą agenci AI bez jasnego kontekstu, pojawia się dodatkowy chaos i wzrasta dług techniczny.

Dlatego dokumentacja od dostawcy oprogramowania nie jest formalnością. To warunek, żeby wiedza o produkcie pozostała dostępna nawet wtedy, gdy zmienią się wszyscy ludzie, którzy nad nim pracują.

Co powinno znaleźć się w dokumentacji projektu IT

Potrzebujesz kilku powiązanych ze sobą elementów: mapa projektu, opis produktu, procesy biznesowe, specyfikacje funkcji, architektura, decyzje techniczne i zasady pracy. Taki zestaw wystarczy, żeby nowa osoba (lub agent AI) wdrożyli się w projekt bez zadawania setek pytań i czytania kodu linijka po linijce.

Po stronie produktu warto wymagać przynajmniej tego:

• Mapa wejścia — gdzie co leży, jak pracować, co czytać i w jakiej kolejności.
• Wizja i cele produktu — w co celować przy planowaniu prac.
• Przepływy biznesowe, typy aktorów i słownik domenowy — bez tego nowi ludzie będą uczyć się systemu od strony interfejsu albo kodu, a to może trwać tygodniami.
• Specyfikacje funkcji — po co dana funkcja istnieje, po czym poznać, że jest gotowa, oraz czego świadomie nie obejmuje w tej iteracji.

Co musi być po stronie technicznej i decyzji

Po stronie technicznej i decyzji warto wymagać przynajmniej tego:

• Opis techniczny „jak to zbudować” — powinien być trzymany oddzielnie od wymagań produktowych. Gdy jedno miesza się z drugim, dokumentacja puchnie i trudniej ją aktualizować.
• Zarys architektury — ogólny obraz systemu, relacje między częściami, miejsca styku. Diagramy w stylu C4 (nawet na wyższych poziomach) pomagają człowiekowi i AI zobaczyć nowe powiązania.
• Stack i standardy — żeby kod był spójny, a code review przewidywalne.
• Dostęp do UX, dokumentacji użytkownika i opisów API (np. Swagger) — jak system ma działać z zewnątrz.
• Decyzje z uzasadnieniem — co wybrano, dlaczego i względem jakich czynników decyzyjnych (np. time-to-market kontra skalowalność). To ujednolica język w zespole: „wydajność” przestaje oznaczać coś innego u każdej osoby.
• Interesariusze — kto jest kim, kogo pytać, jakie są oczekiwania komunikacyjne.
• Otwarty dług i tematy nierozstrzygnięte — osobno od zakresu danej funkcji.
• Krótkie zasady dnia codziennego — możliwe do wyegzekwowania, nie eseje o „kulturze jakości”.

Formę tych materiałów możesz oddać do weryfikacji tech leadowi.

W jakiej formie powinna żyć dokumentacja od software house

Sam fakt, że dokumentacja istnieje, nic nie gwarantuje. Jeśli zespół dostawcy z niej nie korzysta, nie aktualizuje jej wraz ze zmianami w kodzie i nie da się z niej wyciągnąć decyzji, jest bezużyteczna.

W jednym z projektów, które wsparliśmy, ktoś wygenerował „dokumentację” AI jako 70-stronicowy PDF. Nikt nie był w stanie tego przyswoić i zrozumieć, więc wiedza i tak odpłynęła wraz z ludźmi.

Dokumentacja, której warto wymagać, leży zwykle blisko kodu, w miejscu, do którego Twój zespół i dostawca mają dostęp na co dzień.

Jak to sprawdzić? Poproś kogoś po Twojej stronie (np. tech leada albo nową osobę w Twoim zespole), żeby w godzinę odpowiedziała na jedno pytanie: jak wprowadzić drobną zmianę w istniejącej funkcji, bez grzebania w kodzie i na Slacku. Jeśli do odpowiedzi potrzeba trzech rozmów z dostawcą, dokumentacja nie działa. Działa wtedy, gdy da się znaleźć właściwy materiał i zrozumieć ograniczenia bez pytania ludzi u vendora.

Wymagaj, żeby zmieniane z czasem ustalenia nie mieszały się z bieżącym materiałem. Stare wersje mogą zostać w historii repozytorium. W aktualnej dokumentacji programiści i agenci AI powinni widzieć obowiązującą decyzję, a nie kilka wersji z różnych okresów projektu. Szczególnie groźny jest nieustrukturyzowany „śmietnik decyzji”: potencjalnie tysiące linii, w których stara decyzja zostaje w dokumencie, a nowa jest dopisywana niżej. Człowiek sobie z tym poradzi, tylko zajmie mu to więcej czasu. Agent AI wybierze tę wersję ustalenia, która wygląda na optymalną do problemu, który akurat rozwiązuje. I wcale nie musi to być wersja obowiązująca.

Wymagaj więc aktualnej, czytelnej dokumentacji. Nie grubej.

Jak dokumentacja ogranicza dług techniczny, gdy kod piszą agenci AI

Agent AI w projekcie zachowuje się jak bardzo szybko piszący junior, który dołączył na jeden dzień. Jeśli nie dostanie mapy projektu, uzasadnień wcześniejszych wyborów i aktualnych ustaleń, przyjmie założenia na innej podstawie. Na przykład zacznie je wyprowadzać z surowego kodu. Potem napisze kod zgodny z tymi założeniami. W code review może to przejść: lokalnie wszystko będzie wyglądać sensownie. Skutki staną się widoczne trochę później. Kolejne zmiany staną się droższe, a system będzie stopniowo tracił spójność.

Dokumentacja blisko kodu działa jak kontrakt między człowiekiem a AI. Pokazuje agentowi, co czytać, czego nie ruszać i jakie założenia obowiązują. Bez niej agent sam domyka braki w wiedzy i zapisuje je w kodzie, jakby zespół je zatwierdził. Dług techniczny narasta wtedy niepostrzeżenie i szybciej niż przy ręcznym pisaniu kodu.

Osobna sprawa to rozproszenie wiedzy. Jedna decyzja siedzi w Confluence, druga w ticketach, trzecia była ustalona ustnie. Człowiek taką rozproszoną wiedzę jakoś przyswoi. Agent AI zacznie natomiast pracować na tym, co dostanie w kontekście zadania, i na tym, co znajdzie w repozytorium. Dlatego aktualny zestaw dokumentacji blisko kodu sprawdza się lepiej niż wiedza porozrzucana po wielu głowach i kanałach komunikacji.

Nie wymagaj od dostawcy osobnej dokumentacji „pod AI”. Wymagaj tego samego zestawu co przy onboardingu człowieka, tylko w formie, z której agent realnie skorzysta: blisko kodu, aktualnej i bez sprzecznych wersji w jednym miejscu. Im mniej będzie musiał domyślać się sam, tym mniej przypadkowego długu wpadnie do produktu.

Co zyskujesz, gdy dostawca dostarcza aktualną dokumentację

Dokumentacja nie usunie ryzyka. Za to skróci onboarding, ograniczy chaos przy rotacji i ułatwi zmianę partnera technologicznego.

Nowa osoba w Twoim zespole albo u dostawcy nie będzie musiała odtwarzać historii projektu z commitów i Slacka. Wiedza nie zniknie wraz z wypowiedzeniem umowy. Przy zakończeniu współpracy łatwiej będzie wyjść z klasycznego vendor lock-in: sytuacji, w której formalnie masz kod, a praktycznie tylko obecny zespół potrafi go bezpiecznie zmienić. Podniesiesz też bus factor: krytyczny kontekst nie będzie znajdował się w jednej głowie.

Przy pracy z agentami AI będzie mniej domysłów w kodzie i mniej implementacji „bo model tak uznał”. Testy, code review i solidne fundamenty nadal będą potrzebne. Dobra dokumentacja sprawi jednak, że błędne założenia agenta wyjdą wcześniej, a nie dopiero wtedy, gdy szkoda już powstanie.

Sama dokumentacja to za mało: sprawdź stan techniczny produktu

Nawet najlepsza dokumentacja nie uratuje produktu, jeśli chwieją się jego fundamenty: kuleją testy, wdrożenia, monitoring i bezpieczeństwo procesu.

Na szczęście produkty rzadko psują się z dnia na dzień. Ich kondycja spada stopniowo, wraz z przyrostem funkcjonalności. To daje Ci czas na reakcję. Pobierz naszą checklistę stanu technicznego produktu i oceń, co działa, a gdzie są luki, zanim niedociągnięcia staną się kosztowne.

Jeśli wiesz już, czego wymagać od dostawcy w dokumentacji, ale nie masz pewności co do reszty kondycji technicznej, ta checklista będzie dobrym następnym krokiem.

Co zrobić, gdy dostawca nie współpracuje przy przekazywaniu wiedzy?

Jasna lista wymagań wobec dokumentacji sprawdzi się tylko wtedy, gdy dostawca chce współpracować. Jeśli blokuje dostęp, milczy albo obiecuje, że przekaże dokumentację później, to już nie kwestia papierów. To problem operacyjny: nie masz wglądu w produkt, nad którym płacisz.

W jednym z projektów, które przejmowaliśmy, poprzedni dostawca praktycznie nie współpracował, a istniejący kod nie rokował. Musieliśmy szybko przejąć kontrolę nad projektem i odbudować go od podstaw, bo termin był nieprzesuwalny. Formalne przekazanie projektu na papierze by tu nie pomogło.

Jeśli jesteś w podobnej sytuacji, potrzebujesz planu, jak odzyskać kontrolę nad produktem po dostawcy, który nie współpracuje albo nie dowozi. W takich momentach pomaga nasza usługa przejmowania projektów technologicznych: wchodzimy w projekt, porządkujemy stan rzeczy i przejmujemy stery po dostawcy, który zawiódł.

Podsumowanie

Dokumentacja od zewnętrznego dostawcy oprogramowania ma wartość dopiero wtedy, gdy jest kompletna, aktualna i zdatna do użytku bez dodatkowego kontekstu. PDF spisany na starcie projektu się tu nie kwalifikuje.

Taka dokumentacja nie usuwa ryzyka, ale bez niej o wiele trudniej utrzymać produkt, gdy odejdą kluczowi ludzie albo zmienisz dostawcę. Sprawdź więc stan dokumentacji u Twojego dostawcy. Poproś o ścieżkę wdrożenia nowej osoby — gdzie leży dokumentacja i w jakiej kolejności ją czytać — oraz o procesy biznesowe, decyzje z uzasadnieniem i aktualny obraz architektury. Jeśli w odpowiedzi usłyszysz tylko, że „wszystko jest w Confluence”, będzie to sygnał, że dokumentacja nie spełnia standardów.

Podsumuj ten artykuł za pomocą sztucznej inteligencji

ChatGPT

Claude

Perplexity