Na pytanie o optymalny zakres i stopień szczegółowości dokumentacji systemu informatycznego nie ma gotowej odpowiedzi. Skąpa dokumentacja stwarza ryzyko, zbyt rozbudowana - stratę czasu i pieniędzy. Czynnikami, które pomagają określić wymagania odnośnie do dokumentacji, są rodzaj projektu i jego skala. Najlepszym drogowskazem jest jednak określenie, kto i w jakim celu będzie jej w przyszłości używać.

W dyskusjach na temat dokumentowania prac programistycznych padają często skrajne argumenty. Zwolennicy podejścia tradycyjnego dowodzą, że dokumentowanie projektu i kodu, choć czasem żmudne, przynosi wymierne korzyści, i to zarówno wykonawcy, jak i odbiorcy. Przeciwnicy twierdzą zaś, że współczesny kod, w przeważającej mierze obiektowy i powstający przy użyciu dalece zautomatyzowanych narzędzi na podstawie porządnego, formalnego projektu, jest, czy może raczej powinien być, na tyle przejrzysty, że jego dodatkowe dokumentowanie to strata czasu. Czasu, dodajmy, bardzo cennego. Ludowa mądrość uczy, że prawda z reguły leży gdzieś między skrajnościami. Pytanie, gdzie?

Nie tylko kod

Trzeba zdawać sobie sprawę, że dokumentacja w postaci kodu z komentarzem to tylko wycinek większej całości. Współcześnie, w trakcie budowy systemu, powstaje bowiem mnóstwo materiału w taki czy inny sposób opisującego jego kształt. Sporządzanie dokumentacji systemu rozpoczyna się już w momencie negocjacji z klientem. Oczekiwania wobec systemu spisywane są najczęściej w formie tzw. opisu przypadków użycia (use case). W ten sposób dostawca stara się zorientować, co tak naprawdę klient chciałby otrzymać.

Na podstawie wstępnego opisu powstaje projekt funkcjonalny, pomocny w utworzeniu docelowej listy wymagań. W trakcie dalszych negocjacji opis przypadków użycia jest stopniowo przekształcany w szczegółowy opis funkcji przyszłego systemu. Dopiero wtedy zasadne jest tworzenie dokumentacji formalnej, a więc projektu oraz kodu wraz z komentarzem.

W procesie przygotowania oprogramowania powstaje jeszcze dokumentacja testów. Ponadto - po zakończeniu prac - jest tworzona ostateczna dokumentacja administracyjna oraz przeznaczona dla użytkowników. Wielokrotnie okazuje się, że dokumentacja zawierająca opis działania systemu nie jest wcale mniej ważna od kodu - nawet opatrzonego komentarzami. W przypadku rozstania z dostawcą systemu i przejęcia jego obsługi przez nowego partnera kod może nie wystarczyć.

Wszystkim według potrzeb

W praktyce o kształcie dokumentacji decyduje wiele czynników. Najważniejsze wydaje się określenie, kto będzie z dokumentacji korzystać i w jakim celu. Projektanta interesują model formalny i dokumentacja funkcjonalności, natomiast programistę - przede wszystkim kod i zawarte w nim komentarze. Jego celem jest odczytanie roli i wzajemnych zależności poszczególnych bloków programu. Dla wdrożeniowca i administratora istotne będą dokumentacja hierarchii funkcji i obiektów, a także opis dynamiki systemu, np. kolejność aktualizacji tabel przy tworzeniu dokumentu sprzedaży itp. Użytkownik potrzebuje dokumentacji funkcjonalnej, rozbudowanej o instrukcje wykonywania poszczególnych zadań/ról - najlepiej z przykładami w postaci zrzutów ekranowych.

Rozsądek podpowiada, że szczegółowość dokumentowania powinna być adekwatna do rodzaju projektu. Dokumentacja unikalnego produktu przeznaczonego dla każdego klienta będzie zazwyczaj bardziej szczegółowa od tej, dotyczącej systemu przeznaczonego dla szerszej grupy odbiorców. W pierwszym przypadku wyjątkowego znaczenia nabiera opis funkcjonalny, ponieważ tylko dzięki niemu osoba nie będąca autorem systemu ma szansę zrozumieć sens jego działania. Lektura kodu w takich przypadkach to najczęściej za mało.

Niejako naturalnie wymogi dotyczące dokumentowania są zazwyczaj proporcjonalne względem skali projektu, a dokładniej, liczby osób w nim zaangażowanych. Prowadzenie projektu jednoosobowo to dziś rzadkość. Najczęściej zespół projektowy składa się z kilku osób. Przy dużych przedsięwzięciach bywa to kilkanaście, a w skrajnych przypadkach nawet kilkadziesiąt osób. Duża skala projektu powoduje konieczność specjalizacji uczestników i w związku z tym znaczenia nabierają jakość i precyzja komunikacji między nimi. W dużym liczebnie zespole każdy programista skupia się na kodowaniu określonych zagadnień (np. interfejsu użytkownika, warstwy komunikacyjnej, bazy danych itp.), a czasem nawet pojedynczych funkcji. Lekceważenie komentowania kodu lub aktualizacji modelu jest w takich przypadkach traktowane jak przestępstwo.

Na zakres i formę dokumentowania duży wpływ mają używane w projekcie narzędzia. Funkcje dokumentacyjne spełniają, używane praktycznie w każdym średnim i dużym projekcie, pakiety typu CASE (Computer Aided Software Engineering) umożliwiające graficzne modelowanie zależności między obiektami systemu. Ponadto większość zaawansowanych pakietów programistycznych ma wbudowane narzędzia pozwalające na eksportowanie nagłówków obiektów wraz z treścią dotyczących ich komentarzy do zewnętrznych plików (np. PBdoc w PowerBuilder czy Javadoc w narzędziach Java). Jest też ogromna liczba specjalistycznych narzędzi dokumentacyjnych, w tym oczywiście open source, pozwalających np. na graficzną prezentację struktury kodu, podłączanie zewnętrznych plików poprzez hiperłącza, aż po śledzenie wersji dokumentacji i jej automatyczną publikację.