Dokumentacja projektu informatycznego – co powinna zawierać oraz jakich norm warto się trzymać

Zespół, który tworzy i rozwija oprogramowanie, niejednokrotnie całe swoje siły skupia na funkcjonalnościach i wartości użytkowej produktu, nie zwracając zbyt wielkiej uwagi na dokumentację projektową. Jest to działanie niepożądane, szczególnie gdy projekt ma być rozwijany w przyszłości. Dokumentacja projektu to integralna część każdego produktu IT, która pozwala na sprawne aktualizowanie oprogramowania, zmianę jego funkcjonalności, ale też zwiększa ogólną wartość całego projektu. Kiedy i jak powinna być tworzona dokumentacja projektu informatycznego?

 

 

Czy zawsze potrzebna jest dokumentacja projektu?

 

Jednym z najpopularniejszych pytań, które możemy usłyszeć od osób, które mają obowiązek zajęcia się dokumentacją projektu, jest „Czy ta dokumentacja jest naprawdę konieczna?”. Nie istnieje jedyna prawdziwa definicja tego, czym dokumentacja projektowa w istocie jest. W zależności od specyfiki i wielkości projektu dokumentacja projektu może przybrać różne formy oraz standardy.

W praktyce dokumentacja powinna zawierać pewne elementy, które mają pomóc użytkownikom końcowym dowiedzieć się, czym jest dane rozwiązanie, w jaki sposób go używać oraz jak reagować na działania, które oprogramowanie wykonuje. W przypadku projektu, którego adresatem jest klient zewnętrzny, dokumentacja jest integralną częścią produktu końcowego. W tym przypadku zawsze musimy przygotować pełny zestaw, zarówno instrukcji dla użytkowników, jak i dokumentację techniczną dla osób, które mogą w przyszłości zająć się rozwojem produktu.

A co z projektami, których adresatem są pracownicy firmy? Czy oni również potrzebują dokumentacji? Tak, chociaż w innej formie. Pełna dokumentacja w tym przypadku nie jest potrzebna, jednak nikt nie lubi siadać do nowego narzędzia bez wiedzy, jak się nim posługiwać i do czego ono w ogóle służy. Dlatego też w wielu przypadkach prosty plik z instrukcją może być najlepszą formą dokumentacji projektu. Odpowiadając więc na pytanie, czy dokumentacja jest zawsze potrzebna – tak, jednak jej forma uzależniona jest od specyfiki projektu.

 

 

Jak pisać dokumentację projektu programistycznego?

 

Pisanie dokumentacji, jak wcześniej wspomniano, może przebiegać w sposób zależny od tego, jaki projekt jest przez nas opisywany. Inaczej podejdziemy do dokumentacji zaawansowanego produktu, który posiada wiele funkcjonalności i jest adresowany do klienta zewnętrznego, inaczej natomiast do małego makra lub narzędzia, którego celem jest usprawnienie pracy zespołu w naszej firmie. Bez względu jednak na ten czynnik, istnieją pewne ogólnie przyjęte zasady, które sprawią, że każda dokumentacja techniczna projektu informatycznego będzie wartościowa. Jakie to zasady?

  • Dostosowanie formy i stylu do odbiorcy dokumentacji – Osoby, które będą czytać dokumentację projektową, muszą zrozumieć w 100%, na czym polega idea narzędzia, w jaki sposób je obsługiwać oraz na które aspekty należy zwrócić uwagę. Dlatego też język i przekaz musi zostać dostosowany do konkretnej grupy odbiorców. Jeśli dokumentacja jest tworzona na potrzeby rozwiązania wykorzystywanego w innej branży, zadbaj, by treść nie była zbyt techniczna. Tworząc natomiast dokument dla kolegów z teamu, możemy pozwolić sobie na pewne skróty myślowe i wykorzystanie żargonu, jaki funkcjonuje w firmie.
  • Dokument zorganizowany w logiczny sposób – Dokumentacja projektu informatycznego powinna być zorganizowana w taki sposób, by czytając ją od początku do końca, w pełni zrozumieć wszystkie najważniejsze elementy narzędzia. Dokumentacja powinna rozpocząć się od spisu treści, a następnie przechodzić do poszczególnych elementów działania – cel, przeznaczenie rozwiązania, podstawy obsługi, przykładowe problemy, na które możemy natrafić i tak dalej. Dobrze zorganizowana dokumentacja zminimalizuje ryzyko nieporozumień.
  • Język, w którym dokumentacja jest pisana – Prozaiczny, lecz istotny czynnik, który wpłynie na zrozumienie dokumentacji. Z reguły dokumentacja projektowa powinna być tworzona w języku angielskim, szczególnie gdy pracujemy dla zagranicznego klienta lub wśród użytkowników znajdą się osoby obcojęzyczne.
  • Wykorzystanie dedykowanych narzędzi do tworzenia dokumentacji – Dobrą praktyką jest korzystanie z narzędzi, które wspomagają tworzenie dokumentacji technicznej. ReadTheDocs, NaturalDocs czy Dropbox Paper to rozwiązania, które pozwalają na łatwe i szybkie tworzenie oraz edytowanie dokumentacji projektowej.

 

 

Jak zaplanować pisanie dokumentacji?

 

Zaplanowanie tworzenia dokumentacji to bardzo istotny proces, który w dużej mierze wpłynie na jakość dokumentacji i jej odbiór. Z tego powodu nie powinniśmy bagatelizować roli planowania dokumentacji.

Na jakie pytania warto sobie odpowiedzieć, by praca z dokumentacją od samego początku przebiegała bez komplikacji?

  • Kto będzie korzystać z dokumentacji technicznej projektu informatycznego?
  • W jaki sposób chcemy dokumentację napisać? 

Pierwsze pytanie zostało wcześniej szczegółowo opisane. Przyjrzyjmy się drugiemu zagadnieniu, które należy ustalić jeszcze na etapie planowania dokumentacji. Istnieje kilka popularnych form przygotowania dokumentacji technicznej, spośród których powinniśmy wybrać tę, która najlepiej odda idee narzędzia. Powszechnie wykorzystuje się dwie z nich – dokumentacja zadaniowa oraz opisowa. W przypadku dokumentacji zadaniowej skupiamy się na akcjach, które może wykonać użytkownik. Jest to wygodne, szczególnie gdy użytkownik korzysta jedynie z jednego lub dwóch elementów narzędzia i szybko chce zweryfikować obsługę danych funkcjonalności. Styl opisowy polega natomiast na dokładnym opisaniu wszystkich elementów systemu. To kompleksowe podejście, które powinno być stosowane w przypadku dużych narzędzi.

Gdy powyższe kwestie zostały już unormowane, możemy przejść do zbierania wszelkich informacji na temat projektu informatycznego oraz tworzenia dokumentacji.

 

 

Jakie są zalety dobrze napisanej dokumentacji projektu?

 

Wielu programistów z niechęcią podchodzi do pisania dokumentacji technicznej projektu, jednak odpowiednie stworzenie takiego dokumentu niesie za sobą szereg korzyści.

Pierwszą i najważniejszą zaletą jest możliwość odtworzenia każdej funkcjonalności bez względu na to, jak dawno temu narzędzie było projektowane i tworzone. Bardzo rzadko spotkać możemy programistę, który pamięta każdą napisaną linijkę kodu. Gdy po roku otrzymujemy zadanie rozwinięcia funkcjonalności danego narzędzia, za pomocą dokumentacji z łatwością odtworzymy cały proces kodowania, i będziemy mogli w komfortowych warunkach przejść do rozwinięcia kodu. To jednak nie wszystko. Dobrze napisana dokumentacja pozwoli na kontynuację pracy nad rozwiązaniem innym deweloperom, którzy wcześniej nie byli zaangażowani w projekt.

Dobrze napisana dokumentacja do projektu stanowi wartość dodaną, która zostanie doceniona przez klienta. Otrzymanie gotowego rozwiązania z dodatkową dokumentacją sprawi, że zlecenie zostanie wykonane kompleksowo, a klient zadowolony z efektu zechce w przyszłości do nas wrócić.

 

Czy istnieją normy odnośnie pisania dokumentacji projektu?

 

 

Choć styl i forma tworzenia dokumentacji różni się w zależności od firmy, projektu czy osób odpowiedzialnych za to, to jeśli chodzi o projekt informatyczny, dokumentacja może zostać stworzona w oparciu o międzynarodową normę.

Mowa tu o normie ASD-STE100, która pozwala na łatwe zrozumienie tekstu nawet w przypadku, gdy czytelnik nie jest biegły w znajomości języka angielskiego. Na czym polega fenomen projektu technicznego a dokumentacji technicznej, napisanej w zgodzie z normą ASD-STE100?

Jest to uproszczony podzbiór języka angielskiego, który zawiera konkretny zestaw słów angielskich wymaganych, do dokładnego opisania wszystkich elementów danego rozwiązania. Dokumentacja techniczna projektu napisana za pomocą normy ASD-STE100 umożliwia łatwe zrozumienie znaczenia nawet tym osobom, które znają język angielski w ograniczonym stopniu, co znacznie poprawia czytelność i zwiększa dostępność dokumentacji.

 

 

Documentation as Code – co warto wiedzieć o tym podejściu?

 

Wraz ze wzrostem znaczenia dokumentacji projektów informatycznych, powstało kilka bardzo ciekawych praktyk, które w mniejszym bądź większym stopniu zrewolucjonizowały podejście do tworzenia tego typu dokumentów. Jednym z podejść, które z pewnością odbiły się w branży IT największym echem, jest koncepcja Documentation as Code. Na czym polega ta praktyka?

Podejście pozwala nam na tworzenie dokumentacji, która będzie pisana w takim samym stylu jak kod. Jest to coś więcej niż generowanie komentarzy z kodu źródłowego, co wiele firm dotychczas wykorzystywało jako jedyną dokumentację do swoich narzędzi. Podejście Documentation as Code wymaga wykorzystania odpowiednich narzędzi, ale też zmiany całej kultury tworzenia dokumentacji w firmie.

 

 

Jakie są wady źle napisanej dokumentacji projektu?

 

Źle napisana dokumentacja czasem spowoduje więcej szkód niż brak jakiejkolwiek dokumentacji. Dlatego też, jeśli już zabieramy się za stworzenie dokumentu opisującego dane narzędzie, zróbmy to w odpowiedni sposób, zgodny z dobrymi praktykami.

Źle stworzona dokumentacja może wprowadzić w błąd osoby, które w przyszłości mogą zająć się rozwojem funkcjonalności danego narzędzia. To z kolei rodzi ryzyko dokonania niepowołanych zmian w kodzie. Źle stworzona dokumentacja to brak satysfakcji klienta, który otrzymując gotowe rozwiązanie, nie będzie w stanie skorzystać z pełnego potencjału narzędzia. Jeśli więc jesteśmy zobowiązani do stworzenia dokumentacji, podejdźmy do tego z takim samym zaangażowaniem, jak do tworzenia nowego kodu.