Dokumentacja techniczna aplikacji mobilnej — co powinna zawierać, żeby nie zależeć od jednego programisty

Przy przejmowaniu aplikacji widzimy zwykle jedną z dwóch sytuacji. Albo dokumentacji nie ma wcale, a cała wiedza o projekcie jest w głowie jednego programisty. Albo jest gruba specyfikacja z początku projektu, która opisuje aplikację, jaka nigdy nie powstała. W obu przypadkach nowy zespół spędza pierwsze tygodnie na odtwarzaniu wiedzy, a właściciel aplikacji za to płaci.

Dobra dokumentacja techniczna nie jest długa. To kilka krótkich dokumentów, które odpowiadają na pytania zadawane przy każdej zmianie wykonawcy, każdym wydaniu i każdej awarii. Poniżej opisujemy, co powinno się w niej znaleźć i jak sprawdzić, czy to, co masz, w ogóle się do czegoś przyda.

Dokumentacja, która nie pomaga

Zanim przejdziemy do tego, co warto mieć — trzy rodzaje dokumentów, które rzadko pomagają przy utrzymaniu:

• Specyfikacja funkcjonalna z etapu oferty. Opisuje, co miało powstać, a nie to, co faktycznie działa. Po roku rozwoju rozjeżdża się z aplikacją w wielu miejscach.
• Automatycznie wygenerowany opis klas i metod. Mówi, co robi kod, a to widać też w samym kodzie. Nie mówi, dlaczego działa tak, a nie inaczej.
• Dokumentacja, której nikt nie aktualizuje. Nieaktualna instrukcja jest gorsza niż jej brak, bo nowy zespół traci czas na kroki, które dawno przestały działać.

Wartość mają dokumenty, które opisują to, czego nie da się szybko wyczytać z kodu: jak zbudować projekt, gdzie są konta, jak wydać wersję i dlaczego podjęto nieoczywiste decyzje.

Minimum dokumentacji aplikacji mobilnej

Instrukcja uruchomienia

Najważniejszy dokument i najczęściej brakujący. Powinien zawierać:

• wersje narzędzi: JDK, Android Studio, Xcode, Flutter albo Node.js, jeśli dotyczy,
• skąd wziąć pliki konfiguracyjne, których nie ma w repozytorium, np. google-services.json, i kto je wydaje,
• jak przełączać środowiska — testowe i produkcyjne,
• jak uruchomić aplikację na emulatorze i na telefonie.

Sekrety, hasła i klucze nie należą do dokumentacji ani do repozytorium. Dokumentacja mówi tylko, gdzie są przechowywane i kto może je udostępnić.

Mapa systemu

Jeden schemat i krótka lista: aplikacja na Androida, aplikacja na iOS, backend, panel administracyjny, baza danych i wszystkie usługi zewnętrzne — płatności, mapy, powiadomienia, e-mail, analityka. Przy każdej usłudze: do czego służy, na czyim koncie jest i gdzie jest dokumentacja dostawcy. Ta lista przydaje się też przy śledzeniu wycofywanych SDK i API.

Rejestr kont i dostępów

Google Play Console, App Store Connect, Apple Developer, Firebase, chmura, domena, DNS, bramka płatności, dostawca SMS i e-maili. Przy każdym koncie: kto jest właścicielem, kto ma dostęp administratora, na jaki adres przychodzą powiadomienia. Bez haseł — te trzymaj w firmowym menedżerze haseł. Brak takiej listy to najczęstsza przyczyna kłopotów opisanych w tekście o tym, co zrobić, gdy programista zniknął.

Proces wydania

Jak podbić numer wersji, jak zbudować wersję wydawniczą, gdzie jest klucz do przesyłania na Androidzie i czy aplikacja korzysta z Play App Signing, jak podpisać wersję na iOS, na jaką ścieżkę testową wydać najpierw, co sprawdzić przed publikacją. Jeśli wydania są zautomatyzowane, dokument może być krótki, ale nadal powinien mówić, co zrobić, gdy automat nie zadziała. Listę kontrolną przed wydaniem opisujemy w tekście o testach w starej aplikacji, a automatyzację w tekście o CI/CD i fastlane.

Rejestr terminów

Certyfikaty SSL, certyfikat APNs, sekret Sign in with Apple, domeny, umowy z dostawcami, terminy wycofania bibliotek i coroczne wymagania sklepów. Każdy z nich w pewnym momencie wygaśnie i lepiej, żeby był w kalendarzu, a nie w pamięci jednej osoby. Co najczęściej wygasa po stronie serwera, opisujemy w tekście o backendzie aplikacji bez opieki.

Decyzje techniczne

Krótkie notatki o tym, dlaczego coś zrobiono w określony sposób. Format bywa nazywany ADR (Architecture Decision Record): kontekst, decyzja, konsekwencje, data. Najcenniejsze są notatki o obejściach, np. „nie aktualizujemy biblioteki X powyżej wersji 4, bo psuje logowanie na starszych Androidach — zgłoszenie u dostawcy pod numerem…". Bez takiej notatki następny programista zaktualizuje bibliotekę i odkryje problem na produkcji.

Kluczowe ścieżki i integracje

Logowanie, płatności, powiadomienia push i synchronizacja danych opisane na poziomie przepływu: kto wysyła jakie zapytanie, gdzie przychodzi potwierdzenie, co się dzieje przy błędzie, jakie są webhooki. To miejsca, w których awaria kosztuje najwięcej, a kod jest rozproszony między aplikacją, backendem i usługą zewnętrzną.

Opis API

Najlepiej generowany automatycznie z kodu backendu w formacie OpenAPI, żeby nie rozjeżdżał się z rzeczywistością. Do tego zasady wersjonowania i zgodności wstecznej, łącznie z tym, jak działa minimalna wspierana wersja aplikacji.

Znane problemy i dług techniczny

Lista rzeczy, o których zespół wie, że są nie tak, z oceną pilności. Taka lista nie jest przyznaniem się do porażki, tylko planem. O tym, jak ją priorytetyzować, piszemy w tekście o długu technicznym.

Gdzie trzymać dokumentację

W repozytorium, obok kodu, w zwykłych plikach Markdown — np. w pliku README.md i katalogu docs/. Ma to trzy zalety:

• dokumentacja zmienia się razem z kodem, w tych samych zmianach i przeglądach,
• przechodzi do nowego zespołu razem z repozytorium, bez osobnego przekazania,
• nie zależy od narzędzia wykonawcy — wiki na prywatnym koncie agencji znika razem z końcem współpracy.

Wyjątkiem są hasła i klucze: te trzymasz w firmowym menedżerze haseł, do którego dostęp ma więcej niż jedna osoba po Twojej stronie.

Jak utrzymać ją aktualną

• Dokumentacja jest częścią zmiany. Jeśli zmiana dotyczy budowania, wydawania albo integracji, nie jest skończona bez aktualizacji odpowiedniego dokumentu.
• Test nowej osoby. Raz na jakiś czas ktoś spoza projektu próbuje zbudować aplikację wyłącznie na podstawie instrukcji. Każde miejsce, w którym musi zapytać, to błąd w dokumentacji.
• Przegląd raz na kwartał — przy okazji przeglądu zależności i rejestru terminów.

Co zapisać w umowie

• Dokumentacja jako element odbioru prac, a nie dodatek na koniec projektu.
• Przekazanie dokumentacji przy zakończeniu współpracy, razem z kodem i dostępami.
• Prawa do dokumentacji obok praw do kodu — przy przeniesieniu praw autorskich warto, żeby obejmowało ono także dokumentację.

Więcej o tym, co ustalić z wykonawcą, piszemy w tekście o umowie na utrzymanie aplikacji.

Ile to kosztuje

Spisanie minimum dla istniejącej aplikacji średniej wielkości to zwykle 16–40 godzin pracy osoby, która zna projekt, albo nieco więcej, jeśli robi to nowy zespół w trakcie przejęcia. Bieżące utrzymanie dokumentacji to niewielka część każdej zmiany. Dla porównania: brak dokumentacji przy zmianie wykonawcy zwykle kosztuje nowy zespół od kilku dni do kilku tygodni odtwarzania wiedzy — płatnych z Twojego budżetu.

Pięć pytań kontrolnych

Jeśli chcesz szybko sprawdzić, w jakim stanie jest dokumentacja Twojej aplikacji, zadaj sobie i wykonawcy te pytania:

1. Czy ktoś spoza projektu zbuduje aplikację wyłącznie na podstawie instrukcji?
2. Czy wiesz, gdzie są wszystkie konta i kto jest ich właścicielem?
3. Czy proces wydania jest spisany i czy wiesz, gdzie są klucze podpisujące?
4. Czy wiesz, co i kiedy wygasa w ciągu najbliższego roku?
5. Czy istnieje lista znanych problemów?

Każda odpowiedź „nie" to miejsce, w którym aplikacja zależy od pamięci jednej osoby.

Podsumowanie

Dokumentacja techniczna aplikacji mobilnej nie musi być obszerna, żeby była skuteczna. Kilka krótkich dokumentów trzymanych w repozytorium — instrukcja uruchomienia, mapa systemu, rejestr kont i terminów, proces wydania, decyzje i znane problemy — sprawia, że zmiana wykonawcy trwa dni, a nie miesiące, a awaria nie czeka na powrót jednej osoby z urlopu.

Przy przejęciu aplikacji mobilnej uzupełniamy braki w dokumentacji i zostawiamy ją w Twoim repozytorium, a w ramach utrzymania aplikacji aktualizujemy ją przy każdej zmianie. Jeśli chcesz wiedzieć, czego brakuje w Twoim projekcie, zamów bezpłatną analizę aplikacji — wynik dostaniesz na piśmie.