Dokumentacja
Dokumentacja jest dobra. Dokumentację trzeba pisać. A ja doszedłem do takiego dziwnego stanu, że wolałbym spędzać czas obmyślając rozwiązania i pisząc do nich dokumentację, niż dotykając się jakiegoś kodu. Spooky.
Przy okazji nauczyłem się jednej rzeczy -- oczywiście dobrze jest, jeśli tekst można wziąć, przeczytać i nie jest nudny (znaczy -- jeśli dokumentacja techniczna nie jest nudna, to jest bardzo dobrze, ale ja nie o tym) i rzeczywiście, powinien on w jakimś sensie stanowić spójną całość, żeby po przeczytaniu dawał dobre zrozumienie tego, czego dotyczy (czyli nie tylko suche tabelki sqlowe, ale też wytłumaczenie dlaczego one są tak zrobione i jakie są potencjalne drogi dalszego rozszerzania systemu), ale jednak znacznie ważniejsze jest takie podzielenie całości, żeby każdy zainteresowany mógł jak najszybciej znaleźć tę część, która go interesuje. Nawet jeśli to oznacza, że kilka razy trzeba zduplikować jakąś informację. Dokumentacja jest po to, żeby jej używać i jeśli szef projektu chce cię sprawdzić, to rzeczywiście przydaje się mieć taki tekst, dzięki któremu może prześledzić twój tok rozumowania, ale osoby implementujące rozwiązania przeważnie chcą to robić przy jak najmniejszych nakładach czasowych.
Zaczynam dochodzić do wniosku, że dzieląc tekst na kawałki, najlepiej je jak najbardziej łopatologicznie ponazywać, czyli np. do każdego zagadnienia mieć sekcję pod tytułem "Implementacja", gdzie implementator (zna ktoś jakieś lepsze słowo?) dostaje wszystko to, co mu potrzeba i nic więcej (i to z użyciem jak najmniejszej ilości liter). I jak nie masz czasu, to piszesz tylko te kawałki dla implementatorów, bez żadnych "rationale", czy czego tam.
28 VIII 2005 o 11:09:41
Tylko że:
- sekcję o implementacji może prawidłowo napisać tylko dobry koder (ile dałbym, by zapomnieć wszystkie te chwile złe, gdy dostawałem do ręki dokument implementacyjny o wartości zbliżonej do 'if (Zepsute) then Napraw();'
- sekcję o implementacji może przeczytać tylko dobry koder, bo kiepski najchętniej dostałby gotowy kod do copy&paste
- czasami projekt opiera się o tanią siłę roboczą (studentów) i ciężko tam o dwóch dobrych koderów
28 VIII 2005 o 15:52:24
Dokumentacja to przydaje się także autorowi, by po miesiącu czy dwóch nie zapomniał jak pewne rzeczy porobił, jak metody ponazywał, itp ;-)
29 VIII 2005 o 00:34:46
Ale komu tak naprawdę chce się ją pisać? :) Z pewnością nie programiście, bo on woli pisać kod i myśleć nad tym jak to ma działać, dlatego też zatrudnia kogoś innego kto zrobi to za niego, ale ten ktoś niekoniecznie musi być dobrym programistą. A kiedy po jakimś czasie pierwotny autor kodu czyta dokumentację może jej nie zrozumieć! Błędne koło.
Ciekawe jak radzą sobie z tym profesjonaliści?