Szerokie tło z pływającymi stylizowanymi dokumentami i połączonymi ze sobą elementami, idealne do artykułu na temat dokumentacji w tworzeniu oprogramowania.

Dokumentacja a rozwój oprogramowania

21/04/2023

W świecie IT temat dokumentacji zawsze powodował ożywione dyskusje. Niektórzy twierdzą, że jest ona niezbędna w procesie tworzenia oprogramowania, podczas gdy inni są zdania, że to strata czasu i zasobów. Wraz z rozwojem metodyk zwinnych, ten temat często powraca i powoduje duże emocje. Czy zatem dokumentacja jest naprawdę niezbędna w procesie tworzenia oprogramowania i po co jest nam potrzebna?

Dokumentacja i Agile

Tworzenie oprogramowania z wykorzystaniem metodyk zwinnych (Agile) jest często kojarzone z brakiem dokumentacji projektowej, ponieważ mogłaby ona ograniczać zwinność i elastyczność zespołu. To popularne błędne przekonanie wynika z niezrozumienia Manifestu Agile, który idealnie podsumowuję filozofię stojącą za metodykami zwinnymi. W końcu jedna z czterech głównych zasad brzmi "cenimy bardziej działające oprogramowanie nad szczegółową dokumentację".

Jednak czy to całkowicie umniejsza znaczenie dokumentacji? Absolutnie nie! W interpretacji manifestu często pomijany jest komentarz do wyżej wspomnianych zasad, który wyjaśnia, że choć Agile kładzie nacisk na pewne aspekty pracy, to nie neguje przy tym innych. Wyraźnie wskazuje to na wartość klasycznego podejścia do tworzenia oprogramowania, w którym idzie on w parze z tworzeniem dokumentacji.

Jaką dokumentację można stworzyć?

Zdefiniujmy, co rozumiemy przez dokumentację. W kontekście tworzenia oprogramowania, dokumentacja odnosi się do wszelkich pisemnych lub wizualnych materiałów, które opisują projekt, funkcjonalność, wykorzystanie systemu i/lub procesów.

graf przedstawiający podział dokumentacji w procesie tworzenia oprogramowania

Główne dwie kategorie to dokumentacja produktu i procesu. Chociaż obydwa rodzaje dokumentacji są ważne, służą różnym celom i są tworzone na różnych etapach powstawania produktu.

Dokumentacja procesu

Dokumentacja procesu odnosi się do dokumentacji opisującej procesy i procedury wykorzystywane do tworzenia i utrzymywania oprogramowania. Służy ona do zapewnieniu, że wszyscy zaangażowani w proces rozumieją, w jaki sposób zadania mają być wykonywane i jak należy utrzymywać pożądaną jakość. Dokumentacja procesu może zawierać takie elementy jak:

  • standardy kodowania,
  • procedury testowania,
  • zasady kontroli wersji,
  • wytyczne dotyczące code review,
  • harmonogramy,
  • zasoby,
  • ryzyko,
  • plany projektu,
  • harmonogramy,
  • budżety,
  • raporty statusu,
  • plany zarządzania ryzykiem.

Dokumentacja produktu

Dokumentacja produktu odnosi się do dokumentacji tworzonej dla samego oprogramowania. Można ją dalej podzielić na dokumentację dla użytkowników końcowych i dokumentację systemową.

Dokumentacja użytkownika jest używana, aby pomóc użytkownikom zrozumieć, jak zainstalować, skonfigurować i używać oprogramowania. Może zawierać takie rzeczy jak instrukcje obsługi i przewodniki instalacji.

Dokumentacja systemowa ma na celu pomóc programistom zrozumieć, w jaki sposób oprogramowanie zostało zaprojektowane i zbudowane. Zwykle składa się z dokumentu opisującego wymagania, projektu, architektury, kodu źródłowego, specyfikacji technicznych, wytycznych dotyczących testowania, dokumentacji API i wskazówek dotyczących utrzymania. Jednym z najczęściej bagatelizowanych dokumentów jest ten dotyczący wymagań. Dlaczego? Wiele osób twierdzi, że “o tym można zdecydować później”... A takie podejście generuje wiele problemów oraz konieczność wprowadzania dodatkowych iteracji z poprawkami, których można było uniknąć. Dlatego w Primotly przykładamy bardzo dużą wagę do dokumentacji tworzonej na samym początku współpracy i staramy się dokładnie poznać wymagania klienta.

Jak podchodzimy do dokumentacji w Primotly?

Dokumentacja produktu

W naszej pracy kierujemy się zasadami Scrum, dostosowując je do naszych potrzeb. Elastycznie podchodzimy do potrzeb każdego klienta, zachowując przy tym podstawowe procedury usprawniające procesy. Ważnym krokiem w budowaniu z nami produktów jest Initial Workshop, na których zbieramy wszystkie informacje potrzebne do sporządzenia wstępnej dokumentacji projektu. Na tym etapie padną pytania o:

  • ogólną działalność klienta,
  • krótko- i długoterminowe cele biznesowe,
  • wymagania funkcjonalne,
  • wymagania niefunkcjonalne (np. wymagania sprzętowe lub technologiczne),
  • planowane integracje zewnętrzne,
  • możliwe ograniczenia czasowe,
  • przypadki użycia,
  • potrzeby w zakresie UX i UI.

Na podstawie warsztatów tworzona jest pierwsza wersja dokumentacji potrzebnej do oszacowania czasu pracy nad projektem. Czasami pierwsza wersja staje się ostateczną podstawą do prac projektowych, natomiast jeśli klient musi przemyśleć niektóre części, jest ona uzupełniana podczas kolejnych warsztatów.

Choć podstawowe elementy są takie same dla każdego klienta, wstępna dokumentacja często różni się spisem treści i liczbą stron. Wynika to ze złożoności projektu, który może wymagać określenia dodatkowych wymagań już na tym etapie - na przykład rodzaju generowanych raportów czy potrzebnych formularzy.

Każdy klient znajdzie w swojej dokumentacji następujące informacje:

  • Krótki opis klienta, jego działalności, rynku i grupy docelowej.
  • Cele biznesowe projektu.
  • Listę wymagań funkcjonalnych popartą, w razie potrzeby, odpowiednimi materiałami uzupełniającymi, takimi jak przypadki użycia lub diagramy BPMN.
  • Lista zewnętrznych integracji, na przykład z obecnie używanymi programami.
  • Lista wymagań niefunkcjonalnych.

Taki zbiór informacji jest dobrą podstawą do estymacji czasu i kosztów oraz wstępnego zaplanowania prac projektowych.

Jeśli chodzi o pozostałe części dokumentacji systemu – korzystamy z zaawansowanych narzędzi, takich jak Stoplight i GitHub, aby tworzyć dokumentację na bieżąco, co przekłada się pozytywnie na stosunek poświęconego czasu do efektu.

Dokumentacja procesów

Nie oczekuj od nas wielotomowej księgi z niezrozumiałymi opisami procesów i procedur. W naszej pracy priorytetem jest dobra komunikacja, a taki dokument na pewno by jej nie usprawnił.

Zamiast tego korzystamy z dedykowanych rozwiązań ułatwiających pracę, które wielokrotnie przetestowaliśmy we współpracy z klientami. Jira czy Linear pozwalają nam szybko zaprezentować plany czy szacunki, Confluence i Miro pomagają w roadmappingu, a notatki ze spotkań przechowujemy na współdzielonym dysku, dzięki czemu każda osoba zaangażowana w projekt może mieć dostęp do najnowszych wersji dokumentów.

Ważne jest, aby pamiętać, że poziom szczegółowości zawarty w każdym rodzaju dokumentacji będzie się różnić w zależności od potrzeb projektu i konkretnego klienta.

Dokumentacja w Agile

Choć dokumentacja nie jest głównym elementem zwinnego podejścia do tworzenia oprogramowania, to nadal jest niezbędna. Kluczem jest posiadanie elastycznego i usprawnionego podejścia oraz wykorzystanie dokumentacji jako narzędzia do komunikacji i współpracy. W ten sposób zespoły mogą zapewnić, że tworzą właściwe oprogramowanie w sposób wydajny i skuteczny.

Ba
Profesjonalna młoda kobieta o blond włosach, ubrana w okulary w czarnych oprawkach i czarną bluzkę, pewnie oglądająca się przez ramię z lekkim uśmiechem, reprezentatywna dla współczesnego autorstwa artykułu.
Barbara Wojtczak
Project Manager

Najnowsze artykuły

Obraz przedstawiający interfejs aplikacji mobilnej z czerwonymi ikonami i przyciskami, reprezentujący koncepcję mikrofrontendów w artykule "Microfrontend: innowacyjne podejście do architektury frontendu"

Development | 07/06/2024

Microfrontend: innowacyjne podejście do architektury frontendu

Bartosz Białecki

Wyobraź sobie dużą, skomplikowaną układankę reprezentującą całą Twoją aplikację internetową. Każdy element układanki odpowiada określonej funkcjonalności. Teraz, zamiast składać całą układankę za jednym razem, wyobraź sobie, że dzielisz ją na mniejsze, łatwe w zarządzaniu sekcje. Te małe fragmenty to właśnie Microfrontendy.

Szczegóły
Ilustracja CTO na godziny pracującego na laptopie z diagramami przepływu i ekranami kodu, podkreślająca zalety CTO do wynajęcia

Business | 29/05/2024

Jak CTO wspiera innowacje i rozwój biznesu?

Łukasz Kopaczewski

Przedsiębiorstwa, niezależnie od swojej wielkości, coraz bardziej polegają na innowacyjnych rozwiązaniach technologicznych. W tym kontekście rola CTO staje się nie tylko ważna, ale wręcz niezbędna dla każdej organizacji, która pragnie rozwijać się, utrzymać konkurencyjność i osiągnąć długoterminowy sukces. Przyjrzyjmy się zatem głównym powodom, dla których obecność CTO może stanowić kluczowy czynnik w kreowaniu i wzmacnianiu strategii technologicznej oraz osiąganiu celów biznesowych firmy.

Szczegóły
Ilustracja zespołu radzącego sobie z kodem legacy, przedstawiająca trzy osoby współpracujące z kołami zębatymi i rakietą startującą z komputera, symbolizująca strategie skutecznego zarządzania kodem legacy.

Development | 24/05/2024

Jak pracować z kodem legacy? Wskazówki i strategie

Jakub Wachol

Wiele organizacji działa na oprogramowaniu, które ma już swoje lata i zostało napisane w technologiach przestarzałych lub przy użyciu podejść, które obecnie nie są już stosowane. Choć może się wydawać, że to marginalne sytuacje, w rzeczywistości zdarzają się dość często. To właśnie w takich przypadkach pojawia się problem, jak radzić sobie z tzw. "kodem legacy".

Szczegóły