MalyDaemon

Dokumentacja ? Po co ?

Każdy projekt IT trzeba w jakiś sposób dokumentować. Czasem jest to tylko dokumentacja dla użytkownika końcowego, czasem tylko dokumentacja API. Niestety większość osób wogóle nie dokumentuje swoich produktów (mówie to głównie o freelancerach, ponieważ firmy zazwyczaj podchodzą do tego znacznie poważniej). Wszystko jest wporządku dopóki Klient, który posługuje się danym programem, pamięta jak się go obsługuje. Problem pojawia się jak zapomni - zamiast wcześniej przygotować mu dokumentacje, będziemy musieli co chwila odpowiadać na jego pytania.

Rodzaje dokumentacji

Zanim opisze narzędzia wspomagające proces tworzenia dokumentacji, wyróżnię kilka typów dokumentacji:

dla użytkownika końcowego

Przeznaczona jest tylko dla użytkownika, który będzie korzystał z oprogramowania. Musi być zrozumiała dla typowego użytkownika i nie powinna wychodzić poza jego dziedzinę. Nie opisuj swojego cudownego modułu komunikacji z bazą danych - zwykłemu użytkownikowi taka wiedza nie jest potrzebna.

dla administratora systemu (zwana także maintenance manual)

Zawiera informacje istotne z puktu widzenia administratora, który będzie zajmował się bierzącą obsługą systemu od strony technicznej. Powinny się tu znaleźć informacje o konfiguracji oprogramowania, wymaganiach sprzętowych, czynnościach konserwacyjnych.

opis zewnętrznego API

Zawiera opis funkcji używanych przez zewnętrzne programy do komunikacji z systemem. Jest głównie tworzona w przypadku systemów które będą integrowane z zewnętrznym oprogramowaniem.

wewnętrzna

Zawiera dokumentację opisującą wnętrze systemu. Zarówno jego funkcje, jak i data-flow czyli przepływ informacji pomiędzy poszczególnymi modułami. W niej także powinny się znaleźć opisy, wyjaśniające dlaczego dane rozwiązanie programistyczne zostało wykorzytsane. W przypadku skomplikowanych funkcji powinno się je opisać w sposób zrozumiały dla więszości zespołu. Ten typ dokumentacji zazwyczaj nie opuszcza deweloperów (pewnie ze względu na dużą ilość słów niecenzuralnych:)

Narzędzia

Postaram się przybliżyć kilka metod czy narzędzi ułatwiających tworzenie dokumentacji. Niektóre mają dość specyficzne zastosowanie, inne są wmiare ogólne. Konkretny wybór pozostawiam Wam.

Oto dwa założenia którymi się kierowałem przy wyborze narzędzi:

• Musi pozwalać na edycję przez wielu użytkowników
• Musi pozwalać na wyświetlenie różnic pomiędzy wersjami
• Musi obsługiwać kontrolę wersji

Dlatego też na wstępnie odrzuciłem formaty doc i sxw. Nie pozwalają na szybkie pokazanie zmian w dokumencie.

DocBook

Mój ulubieniec. DocBook jest standardem tworzenia dokumentacji, opisów oraz książek (wykorzystywanym między innymi przez O’reilly). Dokument jest tworzony w standardowym edytorze tekstowym przy pomocy znaczników XMLowych. Z pliku źródłowego DocBooka można wygenerować następujące typy plików: pdf, html, rtf.

Ponieważ plik źródłowy to zwykły plik tekstowy, bez problemu można go umieścić w systemie kontrolii wersji.

Moim zdaniem najlepiej nadaje się do tworzenia dokumentacji dla użytkowników, administratorów i API - czyli generalnie rzeczy które są opisywane pod koniec produkcji systemu.

Wiki

Wszelkie systemy popularnie zwane Wiki (najpopularniejszy z nich to MediaWiki na którym opiera się Wikipedia) pozwalają użytkownikom tworzyć i edytować strony internetowe www z poziomu przeglądarki WWW. Istnieje wiele systemów wiki, napisanych w różnych językach (perl, php). Moim faworytem jest wspomniane wcześniej MediaWiki oraz DokuWiki

Zaletą tego narzędzia jest to że informacje są widoczne na stronie odrazu, bez potrzeby transformacji do jakiegoś formatu (jak to miało miejsce w przypadku DocBooka), oraz brak potrzeby instalacji specjalnego oprogramowania. Większość mechanizmów wiki wspiera wersjonowanie stron.

W przypadku wiki pojawia się jednak jeden problem. Jeżeli nie zaplanujemy sensownej struktury dokumentu/dokumentów, znalezienie interesujących informacji może być bardzo trudne.

Moim zdaniem ten typ dokumentacji najbardziej nadaje się do API i dokumentacji wewnętrznej.

Nieśmiertelne komentarze

Są chyba najstarszym i jednym z najlepszych narzędzi dokumetacji. Dzięki nim można dokumentować pliki konfiguracyjne oraz kody programów. Łatwo je umieścić w miejscu do którego się odnoszą, przez co nie trzeba szukać w zewnętrznych dokumentach.

Niektóre języki programowania (Python, Ruby - RDoc ) wspierają tworzenie dokumentacji w formacie HTML na podstawie komentarzy. Łączy to zalety Wiki oraz komentarzy ponieważ mamy zarówno dokumentacje na stronie www jak i w kodzie.

Moim zdaniem najlepiej sprawują się przy tworzeniu dokumentacji API i dokumentacji wewnętrznej.

Podsumowanie

Wybrałem tylko te narzędzia ponieważ w mojej ocenie stanowią one komplet tego co może być potrzene. Oczywiście można wszystko udokumentować w komentarzach czy pliku Worda - ale przecież chodziło o narzędzia ułatwiające tworzenie dokumentacji.

Jeżeli znacie jakieś inne narzędzia, chętnie sie z nimi zapoznam.

Tworząc oprogramowanie bardzo rzadko zastanawiamy się nad procesem przenoszeniem zmian z wersji testowej do produkcyjnej - tzw. deploymentem. W małych systemach zazwyczaj wystarczy przegrać pliki z jednego katalogu do drugiego i załatwia to całą sprawę. Natomiast w większych systemach proces ten jest trudniejszy, ponieważ wymaga bardziej skomplikowanych operacji (np.: aktualizacji struktury bazy danych).

Narzędzia ułatwiające ten proces często dostarczają mechanizmy pozwalające na automatyczną modyfikację plików konfiguracyjnych (np.: definjujących dostęp do bazy), import skryptów SQL do bazy, czy też poprostu wykonanie pewnych poleceń systemowych. Szczególnie jest to przydatne kiedy między wersją testową a produkcyjną są dość znaczne różnice w konfiguracji (np.: ustawienia dotyczące scieżek, cache’a, wersji używanych programów itd). Bez narzędzi wspomagających przeniesienie zmian z jednej wersji do drugiej, łatwo jest zapomnieć o naniesieniu zmian co może spowodować błędne działanie (czy całkowite unieruchomienie) systemu.

Z jakich narzędzi zatem można skorzystać ?

Jednym z podstawowych narzędzi wspomagających deployment może być system kontroli wersji (np.: subversion czy cvs). Dzięki niemu możemy prawie że dowolnie modyfikować wersję testową, zapisać zmiany w repozytorium, następnie zaś w zaktualizwować pliki w innym katalogu.

Drugim narzędziem, bardziej rozbudowanym, jest Phing. Jest to system bardzo rozbudowany. Pozwala na tworzenie zadań, definiowanie zależności międzynimi, wykonywanie poleceń systemowych i wiele innych. Dzięki rozbudowanym mechanizmom, można stworzyć system który spowoduje iż wprowadzenie zmian nie będzie wymagało dużego nakładu pracy (poza skonfigurowaniem Phinga i zdefiniowaniem odpowiednich procedur).

Dwa poprzednie rozwiązania są uniwersalne - można je zastosować praktycznie do dowolnego systemu. Trzecie narzędzie które chciałbym przedstawić jest przeznaczone dla RubyOnRails a nazywa się Capistrano. RubyOnRails jest “fabrycznie” przygotowany do prostego deploymentu. Nawet bez Capistrano jest on przygotowany do przechowywania oddzielnej konfiguracji dla wersji testowych oraz produkcyjnych. Wśrób funkcji które udostępnia Capistrano warto wymienić:

• Automatyczny deployment na inna maszynę (poprzez ssh+svn)
• Przeprowadzenie migracji bazy danych (migracja bazy danych w RubyOnRails to temat na osobny artykuł, ponieważ rozwiązanie jest bardzo ciekawe)
• Rollback - jeżeli po uruchomeniu nowej wersji produkcyjnej pojawi się jakiś błąd to jednym poleceniem możemy powrócić do poprzedniej wersji
• Obsługę farm serwerów

Powyżej wymieniłem tylko kilka narzędzi (zaczynając od najprostszego). Istnieje wiele systemów które w mniejszym lub większym stopniu nadadzą się do tego. Można wyprobować znany z sytemów uniksowych make lub (z tego co wiem przeznaczony dla Javy) ANT czy poprostu napisać skrypt w ulubionym języku programowania.

Jeżeli ktoś z Was zna inne narzędzia przydatne podczas deploymentu to niech podzieli się wiedzą - chętnie je poznam.

Internet Explorer ma bardzo nieprzyjemny błąd polegający na wyświetlaniu białej strony wówczas gdy jest ona skompresowana gzipem - zarówno przy użyciu mod_gzip jak i innych mechanizmów. Kompresja stron pozwala zaoszczędzenie pasma i ich szybsze ładowanie na komputerach Klientów.

Rozwiązaniem tego problemu jest dodanie do nagłowka Content-type wysyłanego przez serwer charset. Przykładowo w PHP wyglądało by to w następujący sposób:

header('Content-Type: text/html; charset=utf-8');

a w RubyOnRails w ApplicationController:


before_filter :set_charset
def set_charset
@headers["Content-type"] = "text/html; charset=utf-8"
end


Pod wysłaniu tak skonstruowanego nagłówka biała strona nie będzie się pojawiać. Oczywiście charset musi być ustawiony na taki sam z jakiego używacie na swojej stronie.

Nie wiem co jest bezpośrednią przyczyną tego błedu, ale był on dla mnie bardzo denerwujący.

Pewnie duża część z Was wielokrotnie spotkała się z problemem negocjacji treści umowy czy ogólnie warunków (zarówno z Klientem jak i Wykonawcą). W większości przypadków nie jest to prosta sprawa. Nie pododam tu recepty dotyczącej udanych negocjacji bo to jest raczej niemożliwe, natomiast podam kilka rad. Rad które przydadzą się zarówno Klientom jak i Wykonwacom.

Zaufanie - jest to moim zdaniem jeden z podstawowych czynników negocjacji. Strony powinny wierzyć w dobrą wolę drugiej strony. Jeżeli takie (napewno ograniczone na początku) zaufanie się nie pojawi, bardzo trudo prowadzi się rozmowy. Na każdy argument pojawi się kontrargument - np.:

Wykonawca

“Wykonaliśmy takie samo oprogramowanie dla XXX w ciągu 180 dni co potwierdzają referencje”

Klient

“Ale to wcale nie znaczy że nam wykonacie w tym terminie”

Szansa że wdrożenie drugi raz identycznego oprogramowania w identycznym terminie nie powiedzie się jest bardzo nieprawdopodobna - przecież część modułów jest już napisana.

Negocjuj tylko z osobami decyzyjnymi - nie rozmawiaj z pośrednikami czy podwładnymi. Mogą się oni zawsze wycofać ze swoich zobowiązań, lub ich szefowie powiedzą że nie byli oni uprawnieni do podejmowania decyzji. Dodatkowo unikniesz problemów związanych ze stronniczym przekazywaniem informacji (przecież pracownik się nie przyzna przełożonemu że zrobił błąd).

Szanuj czas drugiej strony - zawsze proponuj termin spotkania i poproś o jego potwierdzenie. Przy dużych kontraktach podczas negocjacji pojawia się kilka osób i mogą mieć problem z ustaleniem wspólnego terminarza. Nie przekładaj także spotkań w ostatniej chwili - stawia Cię to w bardzo złym świetle (jeżeli natomiast uświadczysz takiej sytuacji od drugiej strony, radze mieć się bardzo na baczności podczas reszty negocjacji).

Pytaj o wyjaśnienia - jeżeli czegoś nie rozumiesz - pytaj. Jeżeli boisz się zapytać wprost “O co Panu chodzi ?”, możesz użyć sformułowania “O ile dobrze Pana zrozumiałem, chodzi Panu o …” - dzięki temu uzyskasz potwierdzenie dobrej interpretacji informacji. Dodatkowo jeżeli negocjujesz umowę żądaj wyjaśnień dlaczego uważają wprowadzenie konkretnych zapisów za konieczne - będziesz miał szanse zrozumieć motywy drugiej strony.

Nie negocjuj z pozycji siły - nawet jeżeli jesteś w dużo lepszej pozycji, nie dawaj tego do zrozumienia drugiej stronie. Pomimo tego że są pewne szkoły negocjacji które uznają tą taktykę za efektywną niesie ona ze sobą duże zagrożenie. Po pierwsze wzbudzasz u drugiej strony poczucie że uważasz ich za gorszych, po drugie zaś może się okazać że po takim przedstawieniu warunków druga strona wstanie i powie “w takim razie dowidzenia”. Oczywiście są sytuacji kiedy wyjście z pozycji siły jest bardzo wskazane, ale są one rzadkie.

Oto kilka rad które mogą pomóc w udanych negocjacjach. Część z nich jest pewnie oczywista, innych oczywistych nie poruszyłem. Chętnie zapoznam się z Waszymi radami dotyczącymi negocjacji w projektach IT (i nie tylko).

Ostatnio dość często pojawiam się na różynch prezentacjach (niestety głównie marketingowych). Zauważyłem że większość prezenterów za bardzo rozwodzi się nad tematem, przezco widownia usypia (nie dosłownie, ale raczej nie dociera do nich przekaz prezentera).

Wiele osób uważa że najlepszą metodą na przyciągnięcie uwagi odbiorcy jest umiesz
czenie jak największej ilości clipartów w prezentacji - których zadaniem będzie rozśmieszenie publiczności. Niestety wygląda to bardzo nie profesjonalnie i ma zupełnie odwrotny skutek.

Moim zdaniem wszelkiego rodzaju prezentacje nie powinny nie trwać dłużej niż 30 minut. Widownia jest najbardziej skoncentrowana na początku i końcu wykładu (pamiętam wykres uwagi: mniej więcej parabola z ramionami do góry, ale nie mogłem go nigdzie znaleźć - może ktos podrzuci linka?). Należy zatem najistotniejsze kwestie powiedzieć w tych przedziałach. W środkowej części można się skupić na technikaliach (jeżeli nie są aż tak istotne) lub na otoczce biznesowej (w przypadku prezentacji technicznych).

W celu “obudzenia” publiczności można spróbować opowiedzieć jakiś przykład wdrożenia z życia wzięty - bynajmniej nie chodzi mi tu o typowy tekst w stylu “Dzięki doskonałej kooperacji z firmą XXX udało nam się w niedługim czasie dokonać wdrożenia u Klienta YYY…”. Najlepiej aby prezenter uczestniczył w takim wdrożeniu i mogł wmiare dokładnie opowiedzieć jaki był problem, jak został rozwiązany i najlepiej jakby jeszcze dodał jakie problemy powstały podczas wdrożenia (ludzie lubią słuchać o problemach innych).

Osobiście podczas prezentacji nie omawaim dokładnie wszystkich aspektów - jedynie naświetlam te najważniejsze i ewentualnie, poźniej podczas dyskusji w kuluarach omawiam je z zainteresowanymi (pamiętaj że nie każdy musi być zainteresowany Twoim wykładem). Takie rozwiązanie pozwala zminimalizowanie czasu prezentacji, maksymalizując ilość informacji jaka zostanie utrwalona przez odbiorców.

Oczywiście podejście do prezentacji jest bardzo indywidualne i zależy zarówno od tego co pokazujemy jak i komu. W Waszym przypadku może to wymagać zmodyfikowania “planu” lub jego całkowitą zmianę.