Dokumentacja w IT – dlaczego oprócz kodu potrzebujesz pliku .doc?

Kiedy chcesz zostać programistą i wykonywać zlecenia IT jako freelancer, w pierwszej kolejności koncentrujesz się na tym, aby dobrze poznać język, w którym będziesz pracował. Uczysz się kodowania, przyswajasz sobie dobre praktyki i dbasz o to, żeby przetestować kod, zanim udostępnisz go innym.

Być może w Twojej pracy napotkasz również zlecenia na programy, narzędzia i pomoce przeznaczone do dalszej rozbudowy lub płynnego współdziałania z już istniejącymi rozwiązaniami. Odbiorcami stworzonych przez Ciebie produktów będą więc inni programiści i koderzy, dla których pytania o to, jak działa Twój produkt i jakie ma funkcje to coś więcej niż abstrakcyjne kwestie.

Tu właśnie w grę wchodzi dokumentacja – plik .doc, który ma przynieść odpowiedzi na pytania i wątpliwości innych użytkowników Twojego kodu, zwłaszcza tych, którzy będą z nim pracować. Nawet jeśli Ty sam rzadko do niej zaglądasz lub nie jest ona na szczycie Twoich zainteresowań, prędzej czy później zetkniesz się z koniecznością jej napisania.

 

Początkujący programista: dlaczego potrzebujesz dokumentacji?

Zanim zajmiemy się tym, kto jest odbiorcą dokumentacji programu i co powinna ona zawierać, zastanówmy się, dlaczego w ogóle jest Ci potrzebna.

Dokumentacja pozwala na relatywnie szybkie poznanie działania i funkcji programu – na przykład biblioteki JavaScript lub frameworka. Użytkownik, który pierwszy raz ma styczność z którymś z tych produktów, potrzebujesz czegoś więcej niż samego automatycznie wygenerowanego API.

Oprócz tej oczywistej funkcji informowania użytkownika, czego może się spodziewać po Twoim produkcie i umożliwienie mu oceny, czy to rzeczywiście tego potrzebuje, dokumentacja jest też pomocą dla Ciebie.
Za pół roku możesz nie pamiętać, co autor miał na myśli w danej części kodu, za co jest ona odpowiedzialna, albo co dokładnie miał robić cały program. Dokumentacja jest więc rodzajem komunikatora między Tobą a przyszłym Tobą lub innymi developerami, którzy będą rozwijać, ulepszać i dostosowywać Twój kod.

 

Dla kogo jest dokumentacja w projektach IT?

Odbiorców dokumentacji można podzielić na dwa typy użytkowników: takich, którzy nie mają nic wspólnego z IT, a potrzebują narzędzia do rozwiązania określonego problemu oraz tych, którzy będą pracować na Twoim kodzie, poprawiać go, rozbudowywać i łączyć ze swoimi rozwiązaniami.

Do tej pierwszej grupy można więc zaliczyć odbiorców wszelkiego rodzaju themes, pluginów templatek stron www, sklepów internetowych, kreatorów witryn lub grafik oraz wszystkich „nieprofesjonalnych” odbiorców programów komputerowych.
Dla nich przygotuj instrukcję użytkowania, która krok po kroku wyjaśni, jak pobrać, zainstalować i obsługiwać Twój produkt.

Druga grupa to najpewniej Twoi koledzy i koleżanki po fachu. Dla nich ważniejsza będzie dokumentacja projektu, bardziej rozbudowana wersja pliku readme, która wyjaśni, jak działa dziennik zmian (changelog), jakie są dobre praktyki, jaką politykę wprowadzania zmian przyjmujesz, jak brać udział w dyskusjach, gdzie zorganizowana jest społeczność użytkowników itp.

 

Co powinna zawierać dokumentacja?

Jeśli masz wątpliwości, dlaczego warto poświęcać czas na pisanie dokumentacji, zapamiętaj na początek, że jej głównym celem jest odpowiedź na pytanie „dlaczego”, a nie „jak” coś zostało zrobione.

Jedną z dobrych praktyk pisania dokumentacji jest… rozpoczęcie od pliku Readme, zanim jeszcze powstanie choćby linijka kodu. Plik Readme powinien zawierać:

• wyjaśnienie, jak działa program i jaki problem rozwiązuje
• linki do zgłaszania bugów
• FAQ i informację, gdzie można zadać dodatkowe pytania lub poszukać wsparcia
• instrukcję, jak zainstalować i uruchomić program
• informacje o licencji

Dokumentacja może rozwijać te punkty, ale również oferować dodatkową wiedzę, która przekłada się na lepsze doświadczenia użytkownika.

Tutoriale. Początkujący użytkownicy doceniają tutoriale. W kontekście programu lub aplikacji tutorial to sposób, aby pokazać, jak ukończyć projekt za pomocą Twojego produktu. Ich głównym celem jest pokazanie użytkownikowi, co może z nim zrobić i jaki efekt uzyskać.

Przewodniki. Przewodnik ma odpowiedzieć na pytanie „W jaki sposób zrobić…?” i opiera się na autentycznych problemach użytkowników, jakie rozwiązuje program. Nie musisz umieć przewidzieć wszystkich sytuacji, w jakich Twój produkt okaże się użyteczny, ale zaprezentuj te, o których myślałeś, tworząc go. Przewodniki tego typu przeznaczone są dla tych użytkowników, którzy mają już pewne doświadczenie w obsłudze programu. Dobrym przykładem są tu przewodniki dla użytkowników profesjonalnych programów graficznych.

Podręcznik (reference guide) to wszystkie informacje techniczne, jakie dotyczą samego kodu – jego funkcje, API itd. Podręcznik powinien zawierać również podstawowe informacje o tym, jak używać programu, jak utworzyć określoną klasę, jak nazywać konkretną metodę itd.

 

Co daje dobra dokumentacja – podsumowanie

Dokumentacja to paradoksalnie jeden z mniej docenianych elementów programu, który jednak ma siłę przeciągania użytkowników i może zaważyć na tym, czy Twój produkt zgromadzi wokół siebie społeczność, a tym samym – czy stanie się popularny.

Aby wysiłek włożony w tworzenie dokumentacji nie poszedł na marne, koniecznie zadbaj, aby była ona łatwa do odszukania w sieci – tu przyda Ci się trochę technik SEO.
Po tym, jak zadbałeś o UX aplikacji lub programu, zadbaj również, aby plik .doc nie odstraszał użytkowników. Im bardziej będzie przejrzysty i im lepiej będzie zorganizowana jego zawartość, tym więcej korzyści oznacza to i dla użytkowników, i dla Ciebie.
Na koniec dopilnuj, aby plik był aktualny i wolny od bugów. Nie ma nic bardziej frustrującego, niż znaleźć instrukcję, która nie działa lub przykład oparty na kodzie, którego nie ma już w aplikacji.

Tworzenie dokumentacji może być wymagające, ale opłaca się i przynosi wymierne korzyści. Pomyśl, o ile łatwiejsze staje się korzystanie z Twojego produktu z dobrym tutorialem, a jak to z kolei wpływa na tworzenie grupy wsparcia developerów gotowych poświęcić swój czas i wiedzę na rozwój stabilnego, wartościowego projektu.