Więcej nie znaczy wolniej cz. 8 - dokumentacja

Na wstępie cytat o tym, że dokumentacja jest jak seks

dokumentacja jest jak...

Dzisiaj zacznijmy od cytatu:

Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing. - Dick Brandon

Osobiście uważam, że nic tak nie oddaje istoty tego, czym właściwie jest dokumentacja.

Jestem prawie pewien, że wielu z Was, gdy musieliście usiąść i napisać jakiś dokument, czy to dla klienta, czy dla siebie (i pozostałych deweloperów) "na przyszłość", niejednokrotnie w myślach wysyłaliście epitety w stronę osoby, która to zleciła.
Niezliczoną ilość razy nie mogliście znaleźć "tej jednej jedynej" istotnej informacji pośród setek zdań, które wydały się na tą chwilę zbyteczne. Pewnie również wielokrotnie trafialiście na "głupoty" oraz "rzeczy oczywiste", którymi dokumentacja była przesączona.
Niekiedy zdarzyło Wam się znaleźć to, czego szukaliście, ale z powodu przebiegu całego procesu pozostawał tylko niesmak. Czasami niesmak ten się potęgował, gdy okazało się, że znalezione informacje są już nieaktualne i... czas spędzony z dokumentacją był czasem zmarnowanym, bo i tak musicie sami znaleźć odpowiedź na dręczące Was pytanie.
Co jednak zrobiliście, gdy już się Wam udało? Zaktualizowaliście dokumentacje? Poprawiliście ją, aby ktoś w przyszłości nie cierpiał tych samych mąk, co Wy? Hmm... pewnie wielu z Was tego mimo wszystko nie zrobiło, bo "przecież dokumentacja jest niepotrzebna". No cóż, w takiej formie z pewnością nie jest tak użyteczna, jak mogłaby być, ale nie ulepszając jej, wpływamy na nią jedynie negatywnie.

A może zdarzyła Wam się sytuacja, że po przeczesaniu kodu, albo po odpowiedzi na pytanie klienta zastanawialiście się czemu #&*@ nikt nie stworzył dokumentacji? Zamiast spędzić x godzin/dni na zrozumieniu wszystkiego, istniałby odpowiedni tekst wyjaśniający całą złożoność problemu. I już prawie napisałeś taki dokument, ale nagle usłyszałeś od managera, że przecież sprawa jest już rozwiązana i teraz to już byłaby zwyczajna strata czasu. No, z taką argumentacją ciężko się kłócić, więc wracamy do pisania kodów, a dokumentacja pozostaje w stanie niezmienionym.

dla klienta i dewelopera

Jeszcze krótki akapit na wstępie gwoli wyjaśnienia dlaczego zdecydowałem się w jednym poście umieścić opis dokumentacji dla klienta i dewelopera.
Wynika to z podobieństw pomiędzy produktami, jedyną różnicą jest odbiorca dokumentów, jednak sam cel posiadania, tworzenia i utrzymywanie ich jakości jest taki sam w obu przypadkach. Stąd właśnie taka decyzja.

dlaczego się jednak opłaca?

Im większy projekt, im większa ilość osób zaangażowanych w jego tworzenie (deweloperzy, managerowie, klienci, itp.), tym większe prawdopodobieństwo i częstotliwość występowania sytuacji opisanych we wstępie. I stwierdzenie, że "teraz jest już po wszystkim" wcale nie jest dobrym argumentem. Z dokumentacją jest jak z kodem - jeżeli jest czytelna i dobrze "poukładana", to z pewnością ułatwi nam pracę w przyszłości, a to, jak wiemy, przełoży się bezpośrednio na oszczędności w czasie i pieniądzach.

I tu można usłyszeć argument, że "nie będzie żadnej przyszłości", ale to już należy do rzadkości i nie wierzę, że dobry manager jest w stanie takie zdanie wypowiedzieć na głos :) A tak poważnie, to nawet zakładając, że nie będzie zmian w wymaganiach i produkt, po zakończeniu przewidzianych prac, nie będzie podlegał modyfikacjom, to z pewnością klient będzie miał jeszcze do nas kilka pytań, może będą jakieś bugi? I wtedy dokumentacja przychodzi nam z pomocą.
W odróżenieniu od testowania, refaktoryzacji, itp., gdzie argumentacja potrzeby tych technik/aktywności opiera się na założeniu, że coś się zmieni bądź kod będzie trzeba modyfikować/rozszerzać, dokumentacja nie wymaga żadnych założeń. Kiedy my skończymy pracę nad produktem, klient odda go w ręce użytkowników, a oni będą musieli go używać, muszą wiedzieć jak (skąd?), mogą mieć pytania, w większości do przewidzenia i powtarzalne (kogo zapytają w celu uzyskania odpowiedzi?) oraz znajdą bugi (kto je będzie naprawiał?). I to już nie są założenia, to się stanie i tekst, który stworzymy podczas produkcji aplikacji może przyjść nam z pomocą.

* z powyższego można wywnioskować, że np. testowanie przydaje się jedynie opcjonalnie, bo przecież nie zawsze będą zmiany, jednak zwróćcie uwagę, że naprawa bugów, to również są zmianym, a im później wracamy do kodu, tym istotniejsze jest ich (testów) posiadanie.
Zwrotu "założenie" użyłem tylko w celu podreślenie tego, jak pewne jest to, że dokumentacja się przyda.

mniej telefonów od klienta

Klient dzwoni, gdy czegoś nie wie. Nie wie czegoś, gdy jest niejasne lub z jakichś powodów niezrozumiałe. A może użytkownicy nie dają sobie rady z produktem? Tak czy inaczej ich pytania trafiają do nas. Dlaczego dzwonią? Z wygody, bo każdy chce zoptymalizować swoją pracę, a dużo łatwiej i szybciej uzyskają odpowiedź od nas niż gdyby sami mieli poszukiwać. W dodatku, informacje uzyskane od nas są pewniejsze, nie opierają się na gdybaniu i odkrywaniu, tylko na wiedzy.

A co gdyby tak dodać do aplikacji linki prowadzące bezpośrednio do odpowiednich fragmentów dokumentacji? Jeżeli owa dokumentacja byłaby przedstawiona w przystępnej formie, to spora część użytkowników, w przypadku pytań, otwierałaby odnośnik i sama radziła sobie z problemem.

Co z klientem i jego wątpliwościami? Odpowiednia struktura i możliwość prostego wyszukiwania w połączeniu z serwowaniem wystarczających i konkretnych informacji również zmniejsza jego potrzebę kontaktu z nami.

Wiele osób woli najpierw spróbować rozwiązywać problemy lub rozwiewać wątpliwości na własną rękę, bo każde pytanie przez wielu, podświadomie, jest odbierane jako przyznanie się do własnej niewiedzy. Oczywiście nie jest to złe (nie wiedzieć czegoś), jednak skoro taka już jest ludzka natura, to wykorzystajmy to dla własnych korzyści i ułatwmy użytkownikom znalezienie odpowiedzi na dręczące ich pytania.

Do tego wszystkiego jeszcze dochodzi kwestia czasu i pieniędzy. Jeżeli klient/użytkownik wie, że szybko może sam uzyskać odpowiedź, to nie będzie tracił czasu na kontakowanie się z nami i czekanie na nią. Umożliwienie znalezienia odpowiedzi na własną rękę to obopulna korzyść - zarówno my, jak i użytkownicy oszczędzamy czas i pieniądze.

szybsza odpowiedź

Jeżeli jednak w końcu sprawa trafia do nas (niekoniecznie do dewelopera, może to być osoba z innego działu odpowiedzialna za kontakt z klientem), to dokumentacja może przyspieszyć czas naszej odpowiedzi, a takie żądanie może pozwolić nam usprawnić obecną dokumentację, tak, aby w przyszłości osoba, która natknie się na podobny problem, była w stanie rozwiązać go bez naszej pomocy.

Wracając jednak do szybkości odpowiedzi. Dlaczego dokumentacja może mieć na to wpływ? Po pierwsze może się okazać, że odpowiedź już w niej jest, tylko przedstawiona w nieodpowiedniej dla klienta w formie. Nasze zrozumienie aplikacji pozwala nam ją dostrzec, a poprzez kontakt z klientem, jesteśmy w stanie ją ulepszyć tak, aby była jasna.

Może się okazać, że problem został opisany w dokumentacji wewnętrznej (z jakichś powodów nie chcemy upubliczniać jego treści) i jesteśmy w stanie odpowiedzieć prawie natychmiast.

łatwiej rozwiązać bugi

Po pierwsze, dzięki dokumentacji, którą posiada klient oraz tej, która jest do wewnętrzengo użytku, wiemy jakie rozwiązania NIE rozwiązują problemu, czyli wiemy, czego on nie dotyczy, a co za tym idzie, wiemy gdzie nie szukać, czyli zawężamy nasz obszar działania.
Po drugie, dokumentacja dla deweloperów pozwala nam na szybsze poruszanie się po miejscach, których od dawna nie widzieliśmy, ułatwia nam odświeżenie informacji i przypomnienie sobie tego, jak cała funkcjonalność działa.

wiedza jest ulotna

Ilość wiedzy, którą posiadamy na temat aktualnie rozwiązywanego problemu/implementowanej funkcjonalności jest dużo większa, niż będzie za tydzień/miesiąc i im dłuższa jest przerwa, tym mniejsza ona będzie i w tym większych ciemnościach się znajdziemy wchodząc na, kiedyś dobrze nam znany, teren.

Umieszczanie istotnych informacji w dokumentacji sprawia, że wiedza nie jest już tak ulotna tzn. nadal znika z naszych głów, ale wiemy, gdzie można ją odnaleźć.

szybszy rozwój aplikacji

Powyższy paragraf pociąga za sobą kolejną rzecz, a mianowicie - szybkość rozwijania produktu. To jasne, że jakość kodów i jego projektu wpływa na tą prędkość, jednak niektóre komponenty mimo wszystko są tak skomplikowane, że bez jakiegokolwiek wprowadzenia i wytłumaczenia co z czym i dlaczego, praca z nimi i tak jest trudna. Przynajmiej do momentu, gdy odzyskamy wiedzę i znowu poczujemy się jak ryba w wodzie. Oczywiście nie muszę już pisać, co może przyspieszyć ten proces :)

o czym warto pamiętać?

Jest kilka ważnych cech dobrej dokumentacji, o których warto pamiętać. Nie będę rozpisywał się na ich temat, bo to nie temat tego wpisu. Mimo wszystko wydaje mi się, że warto je tutaj wymienić:

• obrazki nad tekst
  Większość ludzi to wzrokowcy, więc warto zobrazować to, o co nam chodzi, a nie pisać dziesiątek zdań. Z resztą, jak mówi przysłowie Jeden obraz wart jest tysiąca słów.
  
  
• zwięźle i konretnie
  Nie chodzi o to, że im mniej, tym lepiej, a raczej o odpowiednią strukturę dokumentacji i podział informacji. Nie wyjaśniajcie w danym paragrafie każdego zwrotu, stosujcie odnośniki, słowniki itp. Dokumentacja powinna dawać pełne informacje, nie mniej i nic ponad to, co jest potrzebne.
  
  
• zawsze aktualne
  Dokumentacja musi być odwzorowaniem tego, czym AKTUALNIE jest produkt.
  
  
• don't repeat yourself
  Dlaczego zasada stosowana przy tworzeniu kodu jest również istotna przy tworzeniu dokumentacji? Bo łatwiej wszystkim zarządzać, gdy jest tylko w jednym miejscu, minimalizujemy ryzyko, że zapomnimy o którymś z miejsc.
  
  
• searchability
  Niestety nie znalazłem polskiego (dobrego) odpowiednika dla tego słowa, nie zmienia to jednak faktu, że proste i dokładne wyszukiwanie jest czymś niezwykle istotne. Co z tego, że gdzieś tam jest odpowiedź skoro nie mogę jej znaleźć?
  
  
• linki i słowniki
  To są rzeczy, które ułatwiają korzystanie z dokumentacji. Odnośniki sprawiają, że tekst dotyka tylko jednego tematu, a gdy jest potrzeba, to tworzymy link do odpowiedniego miejsca. Słowniki natomiast minimalizuję możliość interpretacji, każdy rozumie dane wyrażenie w ten sam sposób.
  
  

lepsze jest wrogiem dobrego

Dlaczego wiele osób tak broni się przed jakąkolwiek dokumentacją? Powód jest prosty - kojarzy im się ona z tonami tekstu, który przecież "trzeba przeczytać".
We wcześniejszych akapitach przedstawiłem kilka istotnych cech, którymi powinna się charakteryzować dobra dokumentacja i wierzę, że po całym tekście zdajecie sobie już sprawę, że ani to nie tony, ani nie tekstu, ani nie trzeba wszystkiego czytać.

Jednak teoria to jedno, a w praktyce często realizacja mija się z założeniami. Czy sądzicie, że ktoś tworząc dokumentację ma w planie napisać poemat, którego nikt nie przeczyta? Czy nie zdaje sobie sprawy z tego, że po wielostronicowe dokumenty rzadko sięgamy? W większości przypadków osoba odpowiedzialna za tą czynność chce napisać wszystko zwięźle i krótko, ale... przecież jest tyle informacji, którymi trzeba się podzielić, wiedza, bez której jakakolwiek wędrówka po tekście jest bezwartościowa. Oczywiście można założyć, że osoba czytająca będzie TO wiedziała (czasami wręcz uważamy, że powinna), ale "tak na wszelki wypadek"... a że wypadki chodzą po ludziach, to i tekst nam się rozrasta, aż osiąga rozmiar przerażający.

Czyżbym starał się tutaj powiedzieć, żeby pomijać te informacje i wiedzę? Skądże, jak pewnie zdążyliście już się przekonać, jestem osobą, która wszelkie "oczywistości" i założenia dotyczące wiedzy innych stara się wyeliminować, więc i w tym przypadku staram się dążyć do tego, aby wszystko było jednoznaczne i bezproblemowo zrozumiałe dla każdego przyszłego czytelnika. Ale jak to osiągnąć nie wpływając negatywnie na objętość tekstu? Linki i odnośniki przychodzą z pomocą. Mogą to być linki do źródeł zewnętrznych, jak i bieżącej dokumentacji (która zapewne jakiś podział będzie miała). Jeżeli czytelnik będzie posiadał dane informacje/będzie wiedział daną rzecz, to po prostu nie zatrzyma się w tym miejscu, przeczyta tekst nie zwracając uwagi na odnośniki.
Z powyższego można wywnioskować, że nie zmniejsza to (a przynajmniej nie zawsze) rozmiarów samej dokumentacji i jest to prawda, jednak wpływa na długość poszczególnych rozdziałów, a to przecież najczęściej rozdział nas interesuje, a nie całość.

Objętość dokumentacji jest czymść co odstrasza od niej, ale jeżeli same rozdziały/paragrafy/etc. będą odpowiednio krótkie i konkretne, to ani dodawanie nowych treści ani poruszanie się po nim, nie będzie wywoływało przerażenia na naszych twarzach.

Na dużą ilość tekstu wpływa jeszcze aktualizowanie dokumentacji w przypadku, gdy historię modyfikacji chcemy z jakichś powodów utrzymywać. Czy jednak czytelnik musi koniecznie zapoznawać się z całą historią tekstu? To jest pytanie, na które trzeba sobie zawsze odpowiadać i w zależności od odpowiedzi należy zdecydować, czy trzeba pomyśleć o jak najlepszej formie historii, tak aby czytelnik dostał tylko to, co najważenijsze, a może wystarczy odnośnik? A może repozytorium?

Im produkt żyje dłużej, tym dłuższa będzie dokumentacja (i ta dla klienta i dla deweloperów), lecz nie jest to coś, czego należy się obawiać, to znaczy, że produk rośnie, rozwija się, więc wszystko idzie w dobrym kierunku. Należy jednak dbać o odpowiednią strukturę i powiązania i co jakiś czas sprawdzić, czy wszystko nadal jest tak przejrzyste i przyjemne dla oka, jak być powinno.

<< Poprzednie Następne >>