Jak czytać dokumentację

Jeśli zadajesz pytania, na które odpowiedzi można łatwo znaleźć w dokumentacji, reakcje będą zależeć od atmosfery miejsca pracy, nastawienia Twojego zespołu lub od forum, na którym piszesz. Osoby przyjaźnie nastawione odeślą Cię do źródeł. Natomiast osoby nastawione „mniej” przyjaźnie potraktują Cię skrótowcem RTFM – „przeczytaj tę ekhem przyjazną instrukcję” (ang. Read The Friendly Manual) – albo prześlą Ci link do Let Me Google That For You.

Lepiej nie dopuszczać do takich sytuacji.

Zobaczmy zatem, jak rozwinąć umiejętność czytania dokumentacji.

Otwórz ją

Najważniejsza sprawa – jeśli masz jakiekolwiek trudności w pracy, zacznij od próby znalezienia odpowiedzi w dokumentacji. Największą zaletą takiego podejścia jest skuteczność: w wielu przypadkach w ten sposób znajdziesz potrzebne informacje. Musisz oddać się lekturze i nieco poszperać. Im dalej będziesz na swojej ścieżce zawodowej, tym więcej problemów będzie stawać Ci na drodze – nie ma gotowego przewodnika po wszystkich niuansach programowania.

Masz jakiś problem? I bardzo dobrze!

Większość dokumentacji jest zwykle rzeczowa do bólu, a ich zadaniem jest udzielenie odpowiedzi na ewentualne pytania – nie jest to porywająca lektura. Dużo łatwiej skupić się na niej, kiedy szukasz rozwiązania problemu.

Nie cierpię czytać dokumentacji tylko po to, żeby rozeznać się w projekcie. Nie ma znaczenia, czy chodzi o nowy projekt, czy o nieznaną mi bibliotekę. Mam wrażenie, że to strata czasu, bo nie mam kontekstu, na którym mógłbym się oprzeć, i trudno jest zrozumieć powiązania między rzeczami, o których czytam.

Wolę zrobić coś po swojemu, potknąć się i wrócić do dokumentacji z konkretnym pytaniem. W takim wypadku przynajmniej wiem, czego nie wiem, i jestem zmotywowany do uzupełnienia braków w wiedzy.

Skorzystaj z funkcji wyszukiwania

Aby szybko uzyskać informacje na temat tego, jak rozwiązać problem, na który się natknąłeś, skorzystaj z narzędzi do wyszukiwania.

W przypadku bibliotek zewnętrznych możesz wykorzystać wyszukiwarki, dzięki czemu ograniczysz wyszukiwanie do strony internetowej projektu: po prostu dodaj do wyszukiwanej frazy site:<domain>:

Funkcja ta działa w Google, Bing i DuckDuckGo.

W dokumentacji znajdującej się w kodzie możesz zastosować te same narzędzia, z których korzystasz do przeszukiwania bazy kodu:

• wyszukiwanie w edytorze,
• ripgrep,
• git grep.

Przykład na podstawie git grep:

$ git grep 'http\.post'
src/auto/injector.js: *         $http.post(trackingUrl, trackedEvents);
src/ng/http.js:     *   $http.post('/someUrl', data, config).then(successCallback, errorCallback);
src/ng/http.js:     * - {@link ng.$http#post $http.post}

Ręczne przeszukiwanie dokumentacji ma kilka zalet:

• możesz zapoznać się z jej strukturą,
• znajdziesz wszystkie fragmenty dokumentacji dotyczące Twojego problemu.

Dokumentacja API – suchy opis metod

Samouczek lub przewodnik dają większy kontekst.

Nie rozumiesz? Nic nie szkodzi!

Dokumentacja dokumentacji nierówna. Często nie są one łatwe w odbiorze. Ich twórcy mogą zakładać, że czytelnik posiada już pewną wiedzę o systemie, i nie wszystko będzie wprost opisane. Przez takie sytuacje nowi członkowie zespołu mogą czuć się zbici z tropu.

Najbardziej problematyczne okazują się projekty komercyjne closed source. Jeśli za utrzymywanie bazy kodu i jej dokumentacji odpowiada niewielki zespół, mogą minąć miesiące, zanim przeczyta go nowa para oczu, próbując rozeznać się w tym wszystkim.

Projekty open source są zwykle „łatwiejsze w obsłudze”. Te bez dobrej dokumentacji mają mniejsze szanse na sukces.

Dobry przewodnik nie jest zły

Jeśli w projekcie dostępny jest samouczek albo przewodnik, dobrze jest z niego skorzystać. Jeśli często borykasz się z podobnym problemem, znajdź dotyczący go fragment i po prostu go przeczytaj. Dobrze zrobiony przewodnik da Ci kontekst potrzebny do pełnego zrozumienia wykorzystywanego mechanizmu.

Zanurz się w odpowiedniej części API

Opis API to najbardziej techniczna z dokumentacji. Jest zwykle rzeczowa i brakuje jej opisów kontekstów, w których możesz zastosować konkretną metodę. Przedstawia wszystkie klasy, metody, argumenty i dane wyjściowe będące na Twoim podorędziu.

Jeżeli opis ten jest dostępny, zapoznaj się z różnymi fragmentami dotyczącymi tych samych lub podobnych rzeczy. Często jest tak, że rozwiązanie polega na odesłaniu do innej metody – więc jeśli nadal nic nie wiesz po przeczytaniu jakiegoś fragmentu, sprawdź, czy opis innych metod nie będzie bardziej przydatny.

Wyniki

W przypadku metod będziesz spotykał się albo ze zmianą stanu wewnętrznego obiektu, albo z danymi wyjściowymi. Przewodnik po API powinien dobrze opisywać oba te przypadki.

Zmiana danych wejściowych

Często zdarza się, że metody akceptują dane wejściowe w wielu kombinacjach argumentów. Dokumentacja opisze Ci pełen wachlarz możliwości wprowadzenia wszystkiego, czego potrzebujesz.

Podsumowanie

Czytanie dokumentacji jest istotną umiejętnością, której można się nauczyć tylko przez praktykę. Nie zniechęcaj się, jeśli na początku będzie Ci szło opornie; z czasem będziesz sobie radził coraz lepiej.

Chcesz wiedzieć więcej?

Przeczytaj o tym, jak zajść daleko, stawiając małe kroki.