Dokumentacja nie jest wymaganiem

Nie ma sensu starać się być dokładnym w jakiejś sprawie, jeśli nie wiadomo nawet o co w niej chodzi.

John van Neumann

W swoim życiu zawodowym wielokrotnie spotkałem się z wytycznymi wedle których ,,każdy system musi posiadać dokumentację”. Zwykle na podstawie tak sformułowanych wymagań ktoś z zespołu przygotowywał dokument, który nazywano dokumentacją. Nierzadko był to wymuszony dokument, którego istnienie niczego nie zmieniało w kontekście użyteczności systemu i niczego nie ułatwiało.

W tym poście chciałbym przedstawić moje trzypunktowe podejście do zadań i problemów związanych z dokumentacją.

Po pierwsze, ustal jaki problem ma rozwiązać dokumentacja

Społeczność IT najczęściej postrzega tworzenie dokumentacji jako wymóg konieczny, który w dodatku mało kto chce realizować. Nie dostrzega się najważniejszego zadania dokumentacji, czyli realizacji jakiegoś celu lub sposobu rozwiązania jakiegoś problemu. Bez zastanowienia się nad celem przygotowujemy dokument, który ma zaadresować wszystkie problemy wszystkich interesariuszy, jeśli w ogóle jakieś zaadresuje.

Rozważmy przykładowe cele i problemy, którym sprostać ma dokumentacja:

• Architektura systemu jest złożona i trudno ją wyjaśnić
• Czas wdrożenia pracowników w projekt jest długi i chcemy go skrócić
• Zespół Ops ma trudności z wdrażaniem oprogramowania przygotowanego przez deweloperów
• Inne zespoły narzekają na integrację z naszą biblioteką

Na wszystkie te problemy potencjalnym rozwiązaniem może być dokumentacja. Przyjrzyjmy się im jednak bliżej, co doprowadza nas do drugiego punktu.

Po drugie, czy problem da się rozwiązać inaczej niż dokumentacją

Stworzenie dokumentacji wydaje się często remedium na szereg różnorodnych problemów, ale może warto poszukać i usunąć ich źródło, zamiast przyklejać plaster w formie dodatkowego dokumentu.

Jeśli architektura jest złożona (problem 1), może zamiast pisać rozległą dokumentację tłumaczącą wszystkie zawiłości, lepiej poświęcić swój czas na uproszczenie architektury tak, aby była bardziej zrozumiała.

Jeśli czas wdrożenia pracowników jest długi (problem 2), warto zastanowić się dlaczego tak jest. Czy wynika to ze słabej jakości kodu, nie przestrzegania standardów, braku modularyzacji kodu? Wszystkie te przypadki można rozwiązać inaczej niż dokumentacją, przy okazji upraszczając życie wszystkich użytkowników kodu.

Jeśli wdrażanie systemu przez zespołu Ops jest wyzwaniem (problem 3), może zamiast przygotowywać specyfikację wdrożeniową, zastosować praktyki DevOps. Może zamiast wprowadzać egzotyczne sposoby wdrażania, w firmie istnieje jakiś standard, który można zastosować?

Jeśli zaś problem stanowi użycie biblioteki (problem 4), warto popracować nad API. Przede wszystkim sprawdzić, czy biblioteka ma jasno zdefiniowane API, czy jest ono łatwe w użyciu, czy metody i typy są jednoznaczne.

Po trzecie, wybierz właściwą formę dokumentacji

Nie chciałbym być źle zrozumiany, nie jestem przeciwnikiem słowa pisanego. Niejednokrotnie stworzenie dokumentacji jest najlepszym środkiem do zaradzenia wielu problemom. Warto jednak przemyśleć jej formę. Do opisu frameworka, z którym będą się integrować inne zespoły, najlepszy może być tutorial, natomiast do opisu tego frameworka na potrzeby deweloperów, którzy go rozwijają, tutorial się nie sprawdzi. Do opisu decyzji architektonicznych można zastosować Architectural Decision Records (ADRs). Różne przypadki potrzebują różnych form dokumentacji. Czasami będziemy potrzebowali wielu różnych form w jednym systemie.

Podobnie jest z diagramami. Jeśli diagram nie jest zrozumiały bez osoby go opisującej, zapewne prezentuje zbyt wiele konceptów na raz i powinien być podzielony na kilka prostszych.

Przekaz na dziś

Jeśli ktoś cię poprosi o przygotowanie dokumentacji, zanim coś przygotujesz, zapytaj jaki problem rozwiązujemy i rozwiąż go we właściwy sposób.

---