Dokumentacja w projektach IT to temat, który często budzi pytania i wątpliwości wśród klientów. Czym właściwie jest „dokumentacja”? Jakie są jej rodzaje? Czy jest dodatkowo płatna? Czy kiedykolwiek się przyda? Gdzie ją znajdę? W artykule odpowiadamy na te pytanie (i więcej).
Co rozumiemy przez „dokumentację” w projektach IT?
Dokumentacja w projektach IT jest pojęciem, pod którym rozpoznaje się wiele różnych dokumentów. Nie ma „jednej” dokumentacji, dlatego warto znać wszystkie jej rodzaje oraz potrafić je rozróżniać.
W tym artykule wyjaśnimy czym są cztery najważniejsze rodzaje dokumentacji projektowej. W skrócie są to:
- Dokumentacja funkcjonalna – określa jak oprogramowanie ma działać i wyglądać;
- Dokumentacja techniczna – określa jakie rozwiązania technologiczne zostały wykorzystane i jak z nich korzystać;
- Dokumentacja testowa – umożliwia planowanie, przeprowadzanie i analizowanie testów;
- Dokumentacja użytkownika – tłumaczy użytkownikowi końcowemu jak korzystać z aplikacji tzw. podręcznik użytkownika.
Rodzaje dokumentacji w projektach IT
1. Dokumentacja funkcjonalna
Opisuje, jak aplikacja ma działać i wyglądać z perspektywy użytkowników końcowych.
Dokumentacja ta powstaje na etapie projektowania aplikacji podczas serii Warsztatów Product Design. Zależnie od szczegółowości i rozległości projektu, dokumentacja funkcjonalna będzie obejmować wszystkie lub część elementów z listy poniżej:
- Architekturę Informacji, czyli szczegółową mapę funkcjonalności aplikacji, która pokazuje wszelkie możliwe działania użytkownika w aplikacji oraz sposób, w jaki użytkownicy będą odnajdywać i korzystać z konkretnych funkcji. Ten element przy mało złożonych aplikacjach, które zawierają zaledwie kilka ekranów może zostać pominięty.
- User Stories wraz z Kryteriami Akceptacji to opis funkcjonalności aplikacji z punktu widzenia użytkownika w prostej formie (przykład: Jako <użytkownik> chcę <móc zmienić hasło>, aby <zwiększyć bezpieczeństwo konta>). Na podstawie user stories tworzony jest backlog prac programistycznych na etapie developmentu oraz scenariusze testowe. User stories wraz kryteriami akceptacji daje pewność, że zespół developerski zaprogramuje funkcjonalności oprogramowania dokładnie tak jak tego byśmy chcieli. User stories są również niezwykle ważne aby zweryfikować poprawność działania wytworzonych funkcjonalności.
- Makiety UX/UI, czyli projekt graficzny aplikacji, który wizualizuje jak będzie wyglądał każdy ekran docelowego oprogramowania. To również jeden z niezbędnych elementów, który pozwala programistom wykonać wizualną część projektu. Pokazuje on rozmieszczenie poszczególnych elementów na ekranie aplikacji (UX) oraz docelowy wygląd (UI).
- Bibliotekę komponentów, które pomagają zespołowi developerskiemu w spójnym wdrażaniu elementów interfejsu. Szczególnie ważne przy rozbudowanych i złożonych aplikacjach. W mniejszych projektach, które zawierają zaledwie kilka ekranów może zostać pominięty.
Komu potrzebna jest dokumentacja funkcjonalna i dlaczego?
Pomysłodawcy aplikacji: Daje pewność, że aplikacja zostanie wykonana zgodnie z założeniami, ponieważ każda funkcja planowanej aplikacji jest rozpisana w formie user stories i zwizualizowania w formie makiety graficznej.
Projektantom UX/UI: Dokumentacja User Stories umożliwia zaprojektowanie interfejsu (UX/UI), który jest zgodny z potrzebami użytkowników i założeniami projektu.
Zespołowi developerskiemu: Umożliwia zrozumienie wymagań i precyzyjne wdrożenie funkcjonalności zgodnie z wizją projektu. Dzięki bibliotece komponentów, elementy graficzne są łatwe do zaimplementowania w formie kodu.
Testerom: Dokumentacja User Stories służy jako podstawa do tworzenia scenariuszy testowych i weryfikacji poprawności działania aplikacji na późniejszym etapie.
Gdzie znajduje się ta dokumentacja?
User Stories są najczęściej przekazywane w formie arkusza lub PDF.
Architektura informacji, makiety UX/UI, biblioteka komponentów jest udostępniana w programie do projektowania Figma (w formie linku lub wyeksportowanego pliku).
2. Dokumentacja techniczna
Wyjaśnia techniczne aspekty projekt, w tym użyte technologie, baza danych, połączenia frontendu z backendem itp. Tworzona jest na końcowym etapie powstawania projektu, jeśli istnieje taka potrzeba. Opisuje ostateczne decyzje architektoniczne i rozwiązania techniczne. Taka dokumentacja najczęściej opisuje:
- Architekturę systemu (np. monolit, mikroserwisy, serverless), diagramy architektury;
- wybór technologii (np. Flutter, React.js, .NET, PostgreSQL);
- sposób integracji (np. endpointy API, systemy zewnętrzne);
- struktura bazy danych;
- instrukcje konfiguracji środowisk (np. Docker, CI/CD).
Komu potrzebna jest dokumentacja techniczna i dlaczego?
Zespołowi developerskiemu: aby zrozumieć, jak aplikacja została zaimplementowana, jakie technologie wykorzystano i jak poszczególne komponenty są połączone, aby szybko zdiagnozować problemy, wprowadzać zmiany lub rozwijać aplikację bez ryzyka wprowadzania nowych błędów.
Jest to ważne w przypadku, gdy dalszy rozwój aplikacji ma przejąć inny zespół lub przy wdrażaniu nowego specjalisty.
Gdzie znajduje się ta dokumentacja?
Dokumentacja ta najczęściej przekazywana jest jako plik PDF z opisem poszczególnych zagadnień oraz, w razie potrzeby, z linkami odsyłającymi do narzędzi zewnętrznych (np. dokumentacji endpointów Swagger).
3. Dokumentacja testowa
Opisuje wszystkie aspekty procesu testowania, w tym planowanie, realizację i wyniki testów, aby upewnić się, że aplikacja działa poprawnie. Należą do niej m.in:
- Scenariusze testowe (np. “Czy użytkownik może się zalogować?”).
- Testy regresyjne (sprawdzanie, czy nowe zmiany nie wpłynęły na istniejące funkcje).
- Raporty z testów (np. lista błędów i ich naprawy).
Komu potrzebna jest tak dokumentacja i dlaczego?
Testerom: umożliwia planowanie, przeprowadzanie i analizowanie testów, a także raportowanie ich wyników.
Dokumentacja ta może również być potrzebna programistom (diagnoza i naprawa błędów), managerom projektów (monitorowanie jakości i postępów) oraz klientom, jeśli potrzebują zapoznać się z raportem z przeprowadzenia testów.
Gdzie znajduje się ta dokumentacja?
Przypadki testowe mogą być rozpisywane np. na platformie TestRail lub podobnej, które umożliwiają generowanie raportów.
4. Dokumentacja użytkownika
To prosta, praktyczna instrukcja dla końcowych użytkowników aplikacji (również osób, które będą korzystać z panelu administracyjnego). Przykładami tego typu dokumentacji mogą być:
- Instrukcje jak korzystać z funkcji aplikacji (np. “Jak zmienić hasło?”).
- FAQ (najczęściej zadawane pytania).
- Materiały wizualne, np. zrzuty ekranu lub tutoriale wideo.
Komu potrzebna jest tak dokumentacja i dlaczego?
Użytkownicy końcowi: Dzięki niej wiedzą, jak obsługiwać aplikację i korzystać z jej funkcji (np. zmieniać hasło czy wypełniać raport).
Administratorzy aplikacji: Otrzymują instrukcje dotyczące zarządzania aplikacją (np. dodawania użytkowników, moderowania treści).
Gdzie znajduje się ta dokumentacja?
Najczęściej jest to forma dokumentu online np. na Notion lub w formie PDF.
FAQ – czyli wszystko, co chcielibyście wiedzieć o dokumentacji w projektach IT ale baliście się zapytać
- Czy tworzenie dokumentacji jest dodatkowo płatne?
Dokumentacja funkcjonalna i testowa są integralną częścią tworzenia aplikacji, podobnie jak jej programowanie. Czas, który zespół poświęci na prace nad dokumentacją tego typu, podlega więc opłacie.
W przypadku mniejszych aplikacji dokumentacja użytkownika zazwyczaj nie jest niezbędna. Jeśli zamierzasz rozwijać swoją aplikację z tym samym wykonawcą (software housem), dokumentacja techniczna również jest nieobowiązkowa. Można oczywiście zlecić stworzenie takiej dokumentacji dodatkowo.
Warto ustalić już na etapie zbierania ofert, jakiego zakresu dokumentacji będziesz wymagać. Pozwoli to uniknąć nieporozumień.
- Który rodzaj dokumentacji jest konieczny do stworzenia?
Jeśli planujesz stworzyć aplikację webową lub mobilną, dokumentacją niezbędną do stworzenia będzie dokumentacja funkcjonalna, która określa, jak aplikacja ma działać i wyglądać. Dodatkowo, dokumentacja testowa jest ważnym elementem procesu wytwarzania oprogramowania. Pomaga zespołowi testerów w planowaniu, przeprowadzaniu oraz analizowaniu wyników testów, zapewniając, że aplikacja działa zgodnie z założeniami. Choć dokumentacja testowa jest skierowana przede wszystkim do testerów i członków zespołu odpowiedzialnych za jakość, może być również przydatna dla klienta, ponieważ pokazuje jak aplikacja została sprawdzona pod kątem poprawności działania.
- Jeśli dokumentacja jest płatna, czy mogę poprosić o niewykonywanie jej?
Jeśli wydaje Ci się, że wykonawca proponuje stworzenie dokumentacji o zbyt dużej szczegółowości, możesz zaproponować zawężenie jej zakresu. Jednakże brak jakiejkolwiek dokumentacji, szczególnie funkcjonalnej, jest niezgodny ze sztuką. Brak dokumentacji funkcjonalnej jest jak projektowanie budynku bez pełnej dokumentacji architektonicznej. Samo rozmieszczenie ścian nie wystarczy, aby zrealizować całą inwestycję – potrzebna jest pełna specyfikacja, która uwzględnia wszystkie szczegóły konstrukcyjne i użytkowe.
- Czy backlog to dokumentacja?
Backlog sam w sobie nie jest pełnoprawną dokumentacją. Zawiera listę zadań i funkcjonalności, ale brakuje mu szczegółowych opisów technicznych, procesów biznesowych czy instrukcji użytkownika. Backlog jest potrzebny zespołowi technicznemu, aby sprawnie zarządzać postępem prac.
- Czy mogę zobaczyć przykładową dokumentację z wcześniejszych projektów?
Zazwyczaj możesz otrzymać przykładową dokumentację z wcześniejszych projektów, ale zwykle są to zanonimizowane fragmenty lub wzory dokumentacji, aby zachować poufność danych i zgodność z umowami o zachowaniu tajemnicy.
- Czym się różnią makiety UX/UI od prototypu aplikacji?
Makiety UX/UI to statyczne wizualizacje wyglądu i układu aplikacji, a prototypy to interaktywne modele, które pokazują, jak aplikacja działa. Warto podkreślić, że klikalne modele aplikacji (prototypy) nie są jeszcze zaprogramowanymi i działającymi aplikacjami.
- Czy dokumentacja techniczna będzie dla mnie zrozumiała?
Dokumentacja techniczna jest przygotowywana z myślą o zespole developerów i innych specjalistów, którzy będą utrzymywać i rozwijać aplikację, więc może nie być w pełni zrozumiała dla osoby nietechnicznej. Pamiętaj, że nie jest to jej wadą.
- Czy dokumentacja techniczna będzie pomocna, jeśli zdecyduję się na współpracę z inną firmą w przyszłości?
Tak, szczegółowa dokumentacja ułatwia zrozumienie aplikacji i umożliwia jej rozwój aplikacji przez nowy zespół.
- Kto będzie odpowiedzialny za przygotowanie dokumentacji w ramach projektu?
Zależnie od rodzaju dokumentacji, odpowiedzialność spoczywa na analitykach, projektancie UX/UI, programistach i testerach.
- Ile czasu zajmuje przygotowanie dokumentacji funkcjonalnej i technicznej?
Nie da się jednoznacznie odpowiedzieć na to pytanie. Odpowiedź zależy od złożoności projektu. Dokumentacja funkcjonalna dla prostej aplikacji mobilnej (User Stories, makiety UX/UI) może zostać stworzona w parę tygodni, a dokumentacja techniczna nie zajmie więcej niż parę dni. Im obszerniejszy projekt, tym dłużej potrwa jej wykonanie.
- Czy dokumentacja będzie dostępna w różnych językach, jeśli moja aplikacja będzie międzynarodowa?
Tak, można przygotować dokumentację w wielu językach, jeśli będzie to wymagane. Pamiętaj, że będzie się to wiązać z dodatkowym kosztem.
- Czy komentarze w kodzie są dokumentacją?
Komentarze w kodzie są często stosowane i są pomocne, aby wyjaśnić bardziej skomplikowane operacje, jednak nie zastępują pełnoprawnej dokumentacji funkcjonalnej czy technicznej.
Podsumowanie
Dokumentacja w projektach IT to zbiór różnorodnych materiałów opisujących funkcje, technologię, procesy testowe i obsługę aplikacji. Dokumentacja zapewnia jasność w projekcie, minimalizuje ryzyko błędów i wspiera przyszły rozwój. Jej zakres zależy od złożoności aplikacji. Warto uwzględnić jej koszty już na etapie planowania projektu, ponieważ dobrze opracowana dokumentacja jest ważna dla efektywnej realizacji i przyszłej obsługi aplikacji.
