Dlaczego dokumentacja jest niezbędna? 🤔
Odpowiedniej jakości dokumentacja zapewnia ogromne korzyści organizacji zajmującej się inżynierią. Kod i interfejsy API stają się bardziej zrozumiałe, co zmniejsza liczbę pomyłek. Zespoły projektowe są bardziej skupione, gdy ich cele projektowe i zespołowe są wyraźnie ustalone. Realizowanie procesów ręcznych jest prostsze, gdy dokładnie podano ich kroki. Wprowadzanie nowych członków do zespołu lub zaznajamianie ich z bazą kodu wymaga znacznie mniejszych nakładów, jeśli proces jest przejrzyście udokumentowany.
Ponieważ jednak korzyści związane z dokumentacją siłą rzeczy są widoczne na dalszym etapie, przeważnie jej twórca nie dostrzega od razu ich efektów. W przeciwieństwie do testowania, które (jak się okaże) szybko zapewnia korzyści programiście, dokumentacja wymaga generalnie większych nakładów początkowych, a ponadto dostarcza swemu twórcy wyraźne korzyści w późniejszym czasie. Podobnie jednak jak w przypadku inwestycji związanych z testowaniem, tego typu działania podjęte względem dokumentacji okażą się opłacalne z upływem czasu. W końcu dany dokument możesz utworzyć tylko raz, jednak będzie on później czytany setki, a być może tysiące razy. Koszty początkowe takiego dokumentu będą amortyzowane w przypadku wszystkich kolejnych czytających go osób. Dokumentacja nie tylko jest skalowana z czasem, ale też ma kluczowe znaczenie z punktu widzenia możliwości skalowania reszty organizacji.
Dokumentacja ułatwia udzielanie odpowiedzi na następujące przykładowe pytania:
• Dlaczego podjęto dane decyzje projektowe?
• Dlaczego dany kod zaimplementowano w ten sposób?
• Dlaczego zaimplementowałem kod w ten sposób? (Pytanie to można sobie zadać, jeśli na własny kod spojrzy się dwa lata później).
Jeżeli dokumentacja uwzględnia wszystkie te korzyści, dlaczego przeważnie jest uważana przez inżynierów za „kiepską”? Jak już wspomniano, jednym z powodów jest to, że uzyskiwane korzyści nie są natychmiastowe, zwłaszcza dla twórcy dokumentacji.
Wyróżnić można jednak kilka innych powodów. Oto one:
• Inżynierowie często traktują pisanie dokumentu jako umiejętność inną niż programowanie.
• Niektórzy inżynierowie nie uważają się za zdolnych twórców dokumentacji. Nie trzeba jednak biegle posługiwać się językiem angielskim, aby być w stanie tworzyć nadającą się do użycia dokumentację. Trzeba jedynie się trochę zdystansować i spojrzeć na wszystko z punktu widzenia odbiorców.
• Tworzenie dokumentacji jest często trudniejsze z powodu ograniczonego wsparcia narzędzi lub integracji z przepływem informacji stosowanym przez projektantów.
• Dokumentacja jest postrzegana bardziej jako dodatkowe obciążenie (coś jeszcze, co trzeba utrzymywać) niż coś, co sprawi, że łatwiejsze stanie się utrzymywanie istniejącego kodu.
Nie każdy zespół inżynierów wymaga osoby tworzącej dokumenty techniczne (jeśli nawet byłoby inaczej, nie jest dostępna wystarczająca liczba takich specjalistów). Oznacza to, że inżynierowie będą przeważnie sami pisać większość dokumentacji. A zatem zamiast zmuszać inżynierów do bycia specjalistami od tworzenia dokumentacji, powinno się zastanowić, w jaki sposób ułatwić im to zadanie. Określenie tego, jaki nakład pracy będzie wymagany w związku z dokumentowaniem, to decyzja, jaką organizacja będzie musiała podjąć w pewnym momencie.
Dokumentacja zapewnia korzyści kilku różnym grupom. Następujące korzyści są oferowane nawet twórcy dokumentacji:
• Ułatwia przygotowanie interfejsu API. Pisanie dokumentacji to jeden z najpewniejszych sposobów na stwierdzenie, czy interfejs API ma sens. Często samo utworzenie dokumentacji pozwala inżynierom ponownie ocenić decyzje projektowe, które w przeciwnym razie nie byłyby kwestionowane. Jeśli nie możesz czegoś wyjaśnić i zdefiniować, prawdopodobnie nie zostało to zaprojektowane wystarczająco dobrze.
• Zapewnia wytyczne związane z utrzymywaniem i danymi historycznymi. W każdej sytuacji powinno się unikać stosowania trików w kodzie, ale dobre komentarze są bardzo pomocne, gdy ponownie analizujesz kod utworzony dwa lata wcześniej i próbujesz stwierdzić, co w nim jest nie tak.
• Sprawia, że kod wygląda bardziej profesjonalnie i wzbudza większe zainteresowanie. Oczywiste jest to, że projektanci będą zakładać, że dobrze udokumentowany interfejs API jest lepiej zaprojektowany. Nie zawsze tak jest, choć często obie kwestie są ze sobą mocno powiązane. Choć ta korzyść wygląda na bardziej kosmetyczną, nie do końca tak jest: to, czy produkt dysponuje odpowiednią dokumentacją, stanowi zwykle dobry wskaźnik tego, jak wygodne będzie utrzymywanie produktu.
• Inni użytkownicy będą zadawać mniej pytań. Dla kogoś piszącego dokumentację jest to prawdopodobnie największa korzyść widoczna z upływem czasu. Jeśli musisz wyjaśnić coś komuś więcej niż raz, zazwyczaj sensowne staje się udokumentowanie danego procesu.
Jakiekolwiek byłyby wymienione korzyści dla twórcy dokumentacji, ich lwia część przypada oczywiście jej odbiorcom. W przewodniku firmy Google dotyczącym stylu pisania kodu C++ zawarto maksymę „optymalizuj z myślą o odbiorcy”.
Maksyma ma zastosowanie nie tylko względem kodu, lecz też komentarzy w obrębie kodu lub zbioru dokumentacji powiązanej z interfejsem API. Podobnie jak w przypadku testowania, nakład pracy poniesiony w celu utworzenia dobrych dokumentów przyniesie wielokrotnie korzyści przez cały czas ich użytkowania. Z upływem czasu dokumentacja nabiera kluczowego znaczenia i oferuje ogromne korzyści w przypadku szczególnie ważnego kodu, gdy organizacja zwiększa swoją skalę.
