Dokumentacja – Ktokolwiek widział, ktokolwiek wie.

dokumentacja

„Dokumentacja stanowi jeden z elementów komunikacji w procesie projektowania. W pracy grupowej konieczne jest przekazywanie sobie informacji niezbędnych do realizacji zadań projektowych.”

~Urszula Feliniak, Anna Rogozińska-Pawełczyk

Dokumentacja

Wyobraź sobie, że jako spragniony wiedzy i doświadczeń programista, przychodzisz do nowej pracy, do zespołu pracującego nad dużym ambitnym i kreatywnym projektem. A Ty będąc spragnionym wyzwań, pełnym zapału i potężnie naładowanym pozytywną energią, czujesz się maksymalnie zmotywowany i niecierpliwie przebierasz nóżkami z ekscytacji płynącej z faktu, że od teraz staniesz się jakże ważnym elementem ogromnego przedsięwzięcia.

Poznajesz zespół, załatwiają Ci sprzęt, oprogramowanie i dostępy i w końcu! W końcu możesz usiąść przed kompem, rzucić się w wir pracy i zacząć się wdrażać w projekt.

Odpalasz środowisko, zaczynasz analizować kod i z każdą upływającą godziną coraz częściej zadajesz sobie pytanie „wtf?! O co tu chodzi?”. Kod niczym spaghetti, szkoda że nie rzadko bez komentarzy. Ilu programistów tyle styli formatowania kodu czy nawyków nazewnictwa funkcji. Masa odwołań do funkcji czy miejsc, które zaginęły w czasoprzestrzeni.

Myśl, która zaczyna Cię dręczyć to „wywalić wszystko i zacząć od nowa” jednak rozsądek i uprawnienia biorą górę. Ktoś w końcu poświęcił temu czas i energię by to stworzyć. Działa jak działa, raz lepiej, raz gorzej, czasem w cale, ale jest! 😀 I często trzeba z tym żyć… Na szczęście dostrzegasz światełko w tunelu!

W trafia w Twoje posiadanie dokładny opis założeń i specyfikacji projektu, który niczym dokładna mapa kieruje Cię przez zawiłości mechanizmu, do celu jakim jest zrozumienie tworu, który właśnie analizujesz.

No niestety, takie cuda tylko w bajkach. Dokumentacja mechanizmów niczym Święty Graal bardzo często przy wielu projektach w wielu firmach pozostaje legendą. Każdy o niej słyszał, ale nikt nie widział i nie ma pojęcia gdzie jest. 😛

A jeśli nawet jakieś dokumenty faktycznie istnieją to ich jakość wykonania i użyteczność można porównać do hieroglifów na ścianie czy ksiąg napisanych w pradawnych, zapomnianych już językach.

Niestety, ale problem dokładnie sporządzonej dokumentacji dotyka wielu projektów. A czym większy projekt tym trudniej o dobrą dokumentację, którą ktoś musi sporządzić i utrzymywać, a chętnych do tego szczytnego zadania to można ze świecą szukać.

Nie mniej jednak dobrze skrojony opis funkcjonalności oprogramowania to stabilny grunt dla rozwoju i utrzymania oraz solidny fundament współpracy w zespole. Wdrożenie się w zawiłości mechanizmu i zrozumienie logiki jest znacznie prostsze i szybsze. Pozwala zaoszczędzić wiele czasu i nerwów i płynnie przejść do docelowych zadań. Także kwestia urlopu czy odejścia pracownika nie boli tak bardzo jak w przypadku braku dokumentacji i utraty jedynej osoby, która miała pojęcie o danej funkcjonalności.

Dokładna dokumentacja jest równie ważna co dokładny kod, może nie być nigdy potrzebna, ale w kryzysowych sytuacjach nie raz może uratować projekt. I choć tworzenie jej nie należy do czynności przyjemnych, zwłaszcza dla osób nie mających skłonności do stania się firmowym skrybą. To jednak warto poświęcić jej uwagę i przyłożyć się do stworzenia solidnego zaplecza wiedzy.

Plik readme.md

Przy tworzeniu nowego repozytorium, GitHub umożliwia dodanie do projektu pliku readme.md.

Plik readme.md zazwyczaj jest źródłem wiedzy, dokumentacją (Świętym Graalem :P) o projekcie. Może zawierać informacje o licencji, prawach autorskich, wymaganiach sprzętowych czy zawierać fragmenty kodu jako przykład. Plik ten jest tworzony w języku Markdown i ma rozszerzenie .md.

Język Markdown (.md) to prosty, łatwy i przyjemny język znaczników stworzony w 2004 roku przez John Gruber we współpracy z Aaron Swartz. Stosowany jest często do tworzenia plików readme, pisania postów na forach czy tworzenia tekstów, a także w prosty sposób można przekonwertować plik do HTML czy innych formatów. Markdown został stworzony w myśl zasad „prosty do czytania” (easy to read) i „prosty do zapisu” (easy to write). Do samego języka powstało wiele modyfikacji (np. GitHub) które wzbogacają go o nowe możliwości.

Tworzenie pliku readme.md jest niezwykle proste i już po dosłownie kilku minutach można stworzyć bogato rozbudowany plik za pomocą markdowon.

Przykład.

To co chcemy aby znalazło się w pliku, zapisane w języku Markdown.

język markdown

A efekt wygląda tak:

widok języka markdown

Prawda, że proste :D?

Samo tworzenie pliku jest banalne i można to zrobić np. na stronie GitHub’a bądź skorzystać z edytora Markdown jak np. Dillinger  (w którym został stworzony powyższy przykład).  Natomiast opis możliwości języka Markdown dla GitHub’a  można znaleźć tutaj

Szablon przyzwoitej dokumentacji.

No dobra, wiemy już, że dokumentacja, choć tworzenie jej nie koniecznie jest zajęciem ciekawym i przyjemnym, to jest niezwykle ważnym i warto przyłożyć się do jej stworzenia. Aby była jak najbardziej czytelna, zwięzła i dokładna. A także trzeba pamiętać o aktualizacji jej na bieżąco.

Wiemy, że w przypadku stosowania rozproszonego sytemu kontroli wersji jak np. Git za pomocą np. GitHub’a najlepszym rozwiązaniem jest stosowanie języka Markdown i stworzenie pliku readme.md.

Pozostaje pytanie – „Co powinna zawierać dobra dokumentacja?”

Różne projekty czy mechanizmy różnią się funkcjonalnością, technologią wykonania,  celem przeznaczenia, grupą docelową itp. Dlatego też sama dokumentacja będzie zróżnicowana w zależności od projektu. Jednak jest kilka punktów, które mogą wystąpić w każdej specyfikacji i razem tworzą pewien szablon dobrej dokumentacji.

Opis projektu

Krótki opis aplikacji to niezbędna informacja, która powinna znaleźć się w każdej dokumentacji. Opis do czego służy projekt, jakie możliwości oferuje i do kogo jest skierowany. To informacje, które można uwzględnić w każdym przypadku.

Wymagania techniczne

W dokumentacji warto także zawrzeć informacje o tym jaki sprzęt, środowisko, dodatkowe elementy (jak biblioteki, klient czy sterowniki) są konieczne do poprawnego działania aplikacji.

Sposób instalacji i technologia wykorzystana do stworzenia projektu.

Z pewnością przyda się także informacja jak poprawnie zainstalować aplikacje czy dodać wymagane komponenty. A także w jakich technologiach został wykonany dany projekt.

Opis interfejsu

Jeśli program posiada interfejs to warto opisać jego poszczególne opcje i możliwości.

Opis funkcji, sposób wywołania i przykładowy kod.

Solidna dokumentacja to taka, w której bez wątpienia możemy przeczytać zrozumiały opis poszczególnych elementów mechanizmu, sposób ich użycia. I dobrze też aby w dokumentacji znalazły się jako przykład fragment kodu.

Historia zmian

Przy projektach prowadzonych przez więcej niż jedną, osobę, zwłaszcza gdy zespół jest rozproszony i pracują zdalnie każdy z innego miejsca. Konieczne wydaje się wersjonowanie dokumentacji. Aby każdy w zespole wiedział kiedy, przez kogo i jakie zmiany zostały wprowadzone w dokumentacji.

Informacje o licencji i autorze

Równie istotną informacją jest to, na jakiej licencji jest udostępniany dany projekt i kto jest jego autorem. Jeśli to projekt open source to warto także dodać kontakt do autora na wypadek gdyby ktoś chciał zgłosić błędy bądź dołączyć się do projektu.

Powyżej opisane punkty to jedynie zarys dobrej dokumentacji, do której pewnie można byłoby dopisać jeszcze kilka punktów. Ale te wydają się najbardziej kluczowe i mające miejsce w każdego rodzaju oprogramowaniu.  I też według tego szablonu będzie prowadzona dokumentacja projektu „Ultimp” którą możesz znaleźć w moim repozytorium na GitHub.

A jeśli masz uwagi czy sugestie odnośnie dokumentacji i tego jak powinna wyglądać dobra  dokumentacja to zapraszam do dyskusji w komentarzach. 🙂

You may also like...

5 komentarzy

  1. kj pisze:

    Fajny tekst 🙂 trochę wyłapałem literówek, ale jeden błąd szczególnie gryzie po oczach. To co nazywasz hasztagami nimi nie jest (a ważne w dokumentacji jest to żeby takich błędów nie popełniać). Hashtag wygląda np. tak – #nestyle (# – hash)+(nestyle – tag), a sam hash (pl. kratka) to po prostu #. Pozdrówka i trzymaj się ciepło.

  2. kj pisze:

    „A jeśli masz uwagi czy sugestie odnośnie dokumentacji i tego jak powinna wyglądać dobra dokumentacja to zapraszam do dyskusji w komentarzach.” – a mojego komentarza przez tydzień nie chcesz dodać…

    • Nestor pisze:

      Wybacz, ostatnimi czasy przytłamsiły mnie nieco problemy zdrowotne i lenistwo (z którym usiłuję walczyć :P). Stąd brak aktywności na blogu (niestety 🙁 )
      Ale chce się poprawić, biorę się do pracy i nawet jeśli nie ukończę przed końcem konkursu to chcę dokończyć projekt, przynajmniej do grywalnego prototypu 🙂

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *