- Dlaczego w projekcie brakuje dokumentacji?
- Bo dokumentacja kosztuje, a nikt jej później nie czyta - więc nie piszemy!
- Dlaczego nikt nie czyta dokumentacji, którą mamy?
- Bo nikt dokumentacji nie wierzy! Bo wprowadza w błąd lub jest nieaktualna.
- Dlaczego dokumentacja jest nieaktualna, dlaczego wprowadza w błąd?
- Bo jej pisanie jest uciążliwe i wymaga korzystania z wielu narzędzi.
Tak mogłaby przebiegać rozmowa na temat braków w dokumentacji technicznej w niejednym projekcie.
Szukając w Internecie kluczowych cech użytecznej dokumentacji technicznej można napotkać na artykuły przytaczające wiele różnych cech np. tutaj autorka przytacza aż 8 cech. Próba znalezienia optymalnego poziomu każdej z nich może się wydawać (i zapewne jest) zadaniem karkołomnym, na pewno drogim, a może i niewykonalnym.
Trzymając się starej, rzymskiej zasady mówiącej, że “Omne trium perfectum” - sprowadziłbym to do trzech, podstawowych cech:
Aktualność,
Kompletność,
Ogólność.
Aktualność należy tutaj rozumieć jako zgodność opisu ze stanem faktycznym, czyli niewprowadzanie w błąd, ale również w kontekście upływu czasu, jaki wymagany jest na wyrównanie stanu opisywanej rzeczy z jej dokumentacją.
Kompletność należy tutaj rozumieć jako przekrojowość, czyli opis pełnego przekroju zagadnienia “wszerz”. Naruszeniem tej zasady byłoby np. udokumentowanie metod dostępowych API modułu zamówień systemu ERP, ale pominięcie metod modułu magazynowego.
Ogólność należy tutaj rozumieć jako najwyższy możliwy poziom ogólności, przy którym dokumentacja spełnia na wymaganym poziomie powyższe kryteria.
Celowo nie użyłem słowa “szczegółowość”, gdyż uważam, że dokumentacja wcale nie powinna być szczegółowa. Powinna być na tyle ogólna, aby być użyteczna i przy tym pozostać aktualną i kompletną. Większe przywiązanie do szczegółów niż zdefiniowane powyżej powinno być uznane za marnotrawstwo i w dłuższej perspektywie przyczyni się do erozji i degradacji jakości dokumentacji.
Przykładowo, jeśli w dokumentacji użyję sformułowania “Proszę nacisnąć zielony przycisk Ok” mogę być zmuszony aktualizować ten opis po dodaniu przez zespół UX możliwości przełączenia aplikacji w tryb wysokiego kontrastu, w którym przycisk staje się jasnożółty.
Zamiana na “Proszę nacisnąć przycisk Ok” będąca bardziej ogólną, będzie bardziej odporna na zmiany i sprzyjała utrzymaniu “aktualności” dokumentacji.
Jeśli przyjmiemy, że ideałem jest dokumentacja, która jest w 100% kompletna (opisuje pełen przekrój zagadnienia) i w 100% aktualna (nie zawiera żadnych przekłamań, w tym wynikających ze zmian w czasie) to należy zadać sobie pytanie - jaki poziom ogólności przyjąć za docelowy.
Aby stało się zadość formie manifestu, poniżej lista głoszonych przez niego pryncypiów:
Znajdź swój poziom ogólności metodą od ogółu do szczegółu. Jeśli poziom ogólności jest Ci narzucony, miej świadomość kosztu tworzenia użytecznej dokumentacji na tym poziomie,
Pisz krótko, zwięźle. Unikaj okazji do niejednoznaczności, wielorakich interpretacji. Jeśli to możliwe - rysuj, używaj notacji i języków modelowania (BPMN, UML),
“Make it easy to do the right thing” - usuwaj przeszkody i utrudniacze w procesie. Trudne w użyciu narzędzia zamieniaj na prostsze. Spraw, aby dokumentacja znajdowała się blisko opisywanego rozwiązania,
Automatyzuj co się da - eksport dokumentu, aktualizacja atrybutów, wersjonowanie, generowanie opisów API na podstawie kodu źródłowego itp.,
Unikaj skomplikowanych, nadmiarowych szablonów dokumentów. One często sugerują nieadekwatny poziom szczegółowości, budują złudne poczucie kompletności dokumentacji. Szablony zastępuj checklistami, które zasugerują Ci jakim zagadnieniom powinieneś poświęcić czas;
Staraj się zachować stały poziom ogólności w całym dokumencie. Jeśli pewne obszary należy udokumentować bardziej szczegółowo, zachowaj jeden poziom szczegółowości w tych obszarach;
Jeśli goni Cię czas lub budżet i musisz z czegoś rezygnować, to najpierw z poziomu szczegółowości dokumentu. Jeśli nie możesz - z poziomu szczegółowości konkretnych obszarów. Możesz zmniejszyć częstotliwość aktualizowania dokumentacji. W ostateczności - rezygnuj z kompletności dokumentu, pomiń pewne zagadnienia jasno komunikując w dokumentacji czego ona nie zawiera. Nigdy nie rezygnuj z ze zgodności z prawdą. Nie ma nic gorszego niż dokumentacja, która kłamie.