KosciaKowy blog

Chyba każdy zna starą maksymę "Gdy już wszystko inne zawiedzie, przeczytaj instrukcję". Niestety mam wrażenie, że zdecydowana większość stosuje się do niej i nie widzi w tym niczego zdrożnego. Muszę się przyznać, że do czasu gdy zacząłem zajmować się programowaniem, sam tak najczęściej postępowałem. A przecież to najgłupsza rzecz jaką można zrobić!

RTFM!

Zdjęcie autorstwa adactio na licencji CC-BY

Jeśli ktoś nie wie, RTFM to akronim oznaczający Read The FuckingFriendly Manual (z ang. Przeczytaj Tę PieprzonąPrzyjazną Dokumentację). Dawnymi czasy na grupach Usenetowych tak właśnie zachęcano do przeczytania dokumentacji, zwłaszcza jeśli pytanie dotyczyło rzeczy mniej lub bardziej oczywistych. Podejrzewam, że dziś nadal można ten, zwrot usłyszeć na wielu forach. Może nie jest to sposób zbyt przyjemny sposób by skierować kogoś do dokumentacji, jednak najczęściej skuteczny.

Bo czytanie dokumentacji musi wejść w krew. Fakt, że instrukcje nie zachęcają do czytania niczego tu nie zmienia. Nawet jeśli są pisane jak dla idiotów (lub przez idiotów), albo pełne technicznych, niezrozumiałych zwrotów i tak warto do niej zajrzeć. Już tłumaczę dlaczego.

Szanuj swój czas

Tu nie chodzi o dogłębne studiowanie instrukcji i uczenie się jej na pamięć. Wystarczy pobieżnie przejrzeć spis treści, przeskanować wzrokiem tekst i spojrzeć na rysunki oraz diagramy. To już wystarczy by móc się zorientować z czym mamy do czynienia i poznać wszystkie najważniejsze funkcje. A co najważniejsze już wiemy, co się w dokumentacji znajduje i czy w przyszłości w ogóle jest sens po nią sięgać.

"Ukryte", nieoczywiste funkcje

Ile razy zdarzyło ci się, że po długim czasie korzystania z jakiejś rzeczy, po przypadkowym naciśnięciu przycisków, odkryłeś funkcję, której tak brakowało? Ile razy zdarzyło ci się, że korzystając z jakiegoś programu lub serwisu, odkryłeś że jest dużo prostszy sposób na wykonanie różnych żmudnych czynności, które zajmowały spore ilości czasu? Najczęściej to wszystko jest w miarę dobrze wytłumaczone, wystarczy tylko przeczytać.

Nie daj się zaskoczyć

Przejrzenie dokumentacji pozwala przygotować się na potencjalne problemy. Najczęściej znajdziemy tam uwagi na co uważać by nie dopuścić do pojawienia się problemów. A gdy pojawi się jakiś problem już wiemy czy znajdziemy jego rozwiązanie w instrukcji czy nie. Po co szukać po omacku rozwiązania (ryzykując pogorszenie się sprawy), lub czekać aż ktoś nam odpowie jeśli mamy je od początku podane na tacy.

Szanuj czas innych użytkowników

Nie ulega wątpliwości, że pomaganie innym daje sporo frajdy. Sam bardzo lubię pomagać innym. Jednak krew mnie zalewa, gdy kolejna osoba z rzędu pyta o coś co łopatologicznie wytłumaczone jest w pliku pomocy, czy w FAQ. Jeżeli tobie nie chciało się poświęcić kilku minut na przejrzenie dokumentacji, gdzie dany problem jest wyjaśniony, dlaczego innym ma się chcieć poświęcić swój czas tobie. Czas, który mogliby poświęcić pomocy komuś, kto tego rzeczywiście potrzebuje.

Szanuj czas producenta

Myślisz, że napisanie dokumentacji jest prostą sprawą? Niestety jest to proces żmudny i nudny. W dodatku pochłaniający sporą ilość czasu, którą można by wykorzystać na poprawienie samego produktu. A trzeba pamiętać, że wraz z wprowadzaniem zmian dokumentację trzeba aktualizować. Jeśli więc do produktu, programu, czy biblioteki jest dołączona dobra, aktulna dokumentacja należy to docenić i do niej zajrzeć.

Przekonany?

Ja już nie wyobrażam sobie jak można nie zaczynać od przeczytania dokumentacji. Obojętnie czy jest to opis API biblioteki programistycznej, instrukcja jakiegoś urządzenia, plik pomocy zainstalowanego programu, czy FAQ serwisu internetowego. Nawet czytanie książki (zwłaszcza technicznej) zaczynam od przeczytania ostatniej strony, spisu treści i pierwszego rozdziału objaśniającego zastosowane konwencje.

A na koniec tylko dodam, że w przypadku bardzo wielu aplikacji i bibliotek programistycznych w dokumentacji znajdziemy o wiele więcej niż w wielu książkach, za które musielibyśmy słono zapłacić.