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żeli 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 systemu 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 cza 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 adekwatną 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żeli diagram nie jest zrozumiały bez osoby go opisującej, prawdopodobnie 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 adekwatny sposób.
