Aplikacja przygotowana z głową

Co to jest dokumentacja techniczna

Pewnie osoby nie techniczne zastanawiają się co to jest ta dokumentacja techniczna i dlaczego powinni na nią zwracać uwagę. Myślę że najłatwiej porównać ją do innych dokumentacji przygotowywanych np. w trakcie prowadzenia budowy budynku lub innej infrastruktury. W przypadku budowy domu bez takiej dokumentacji technicznej jest niemożliwym rozpoczęcia prac ze względów prawnych. Czy ktokolwiek z Was zastanawiał się dlaczego urzędnicy tego wymagają? Oczywiście powodów jest wiele ale ja posłużę się jednym czynnikiem - bezpieczeństwo. Jeżeli potencjalny projekt miałby zagrażać życiu lub zdrowiu ludzi to oczywiście taki projekt nie zostanie zatwierdzony.

Ok mówimy dużo o projekcie technicznym budynków ale o co chodzi z dokumentacją techniczną aplikacji? Otóż jest podobnie. Taka dokumentacja powinna zawierać najważniejsze założenia dotyczące aplikacji takie jak:

• środowiskach i na jakich systemach dana aplikacja ma działać,
• jaki potencjalnie ruch ma obsługiwać,
• no i oczywiście najważniejsze, czyli opis funkcjonalności.

Jeżeli posłużymy się analogią bezpieczeństwa w projektach budowlanych to taka dokumentacja techniczna aplikacji daje poczucie bezpieczeństwa obu stronom, zamawiającemu i wykonawcy, każda ze stron wie czego może się spodziewać. Czyli reguła win - win.

Jak już wiemy co to jest to przejdźmy do kolejnej nurtującej kwestii - dlaczego potrzebujemy dokumentacji technicznej? Co może nas motywować do jej stworzenia? Ludzie z reguły są leniwi, i bardzo dobrze, bo do tej pory mieszkalibyśmy w jungli i polowali na mamuty, a dzięki temu że jesteśmy leniwi to mamy to co mamy, czyli technologie, medycynę i inne zbytki, zapełniające nasze życie jak xbox lub tik tok :)

Skoro ludzie są leniwi to trzeba znaleźć jakiś inny sposób aby tworzyć bardzo dobre jakościowo produkty. Rozwiązaniem na to są wszelkie zapisane ustalenia. Jeżeli jakiś projekt trwa więcej niż kilka tygodni to ciężko zapamiętać wszystkie szczegóły które zostały na początku ustalone. Gdybyśmy tego nie spisali to albo stracilibyśmy bardzo wiele czasu na ponowne ustalania albo powtórne ustalanie czegoś mogłoby wpłynąć negatywnie na już istniejące elementy aplikacji. Gdy tworzymy dokumentację to od początku wiemy jak ma działać dana aplikacja i już na tym etapie jesteśmy w stanie wyłapać niezgodności lub konflikty w poszczególnych modułach systemu, a im wcześniej je znajdziemy tym więcej zaoszczędzimy.

Kto powinien przygotować dokumentację?

Uważam osobiście po wielu latach doświadczenia, że dokumentację powinny przygotowywać obie strony kontraktu. Zamawiający najlepiej wie czego chce, a wykonawca powinien wesprzeć swoją techniczną wiedzą zamawiającego.

Każdemu kto zajmuje się zawodowo projektowaniem i tworzeniem aplikacji zachęcam do stworzenia swojego szablonu dokumentacji technicznej, ze swojej strony w dalszej części artykułu wskaże co powinno się znaleźć w takiej dokumentacji.

Dlaczego zachęcam do stworzenia takiego szablonu? Ponieważ pomoże to obu stronom ubrać swoje potrzeby w pewne ramy. Niejednokrotnie spotykałem się z tym, że klienci przychodzili do mnie z 30 stronicowymi dokumentami opisującymi w bardzo lakoniczny sposób jak ma działać aplikacja pomimo że było tam tak dużo treści. Wpisanie tego w odpowiedni szablon pomoże obu stronom zapanować nad niepotrzebnym słowotwórstwem, które w żaden sposób nie wpływa na opis funkcjonalności.

Oczywiście zamawiający nie zawsze może dysponować odpowiednią wiedzą, a także czasem aby opisać wszystko dokładnie, dlatego podział tych obowiązków powinien być ustalony na samym początku i myślę że należy w tym pierwszym etapie być bardzo elastycznym. Dobrym pomysłem jest organizowanie wspólnych sesji aby omawiać poszczególne etapy tworzenia tejże dokumentacji.

Czy potrzebuje projektu graficznego przy tworzeniu dokumentacji technicznej?

Myślę że przyda się tutaj krótkie wprowadzenie, co to jest projekt graficzny aplikacji webowej. Jak można się domyślać jest to obraz lub zbiór obrazów (grafik) przedstawiająca jak będzie wyglądać aplikacja. Jeżeli ktoś spotkał się już z projektem graficznym strony www to oczywiście może sobie łatwo wyobrazić czego się spodziewać. Należy jednak zaznaczyć że przy projektach graficznych aplikacji nie stawiamy aż w takim stopniu na przepiękną grafikę samą w sobie, ale na użyteczność aplikacji.

Jeżeli mowa o użyteczności to jednym z motywów popychających nas do stworzenia projektu graficznego jest przekonanie się czy nasza aplikacja będzie wygodna dla użytkowników zanim ją zaczniemy budować. W ten sposób zaoszczędzimy mnóstwo czasu gdybyśmy nagle pod koniec prac nad aplikacją uznali że pewne jej elementy nie są funkcjonalne z punktu widzenia przyszłego użytkownika.

Skoro wiemy już czym kierować się przy podejmowaniu decyzji czy zlecić przygotowanie projektu graficznego to musimy sobie jeszcze odpowiedzieć na pytanie: Kto powinien go przygotować? Od razu nasuwa nam się odpowiedź - Grafik. To jednak nie jest do końca poprawna odpowiedź, gdyż są różni graficy. Projekt aplikacji powinien głównie przedstawiać przepływ danych oraz w jaki sposób przyszli użytkownicy będą posługiwać się naszą aplikacją, dlatego przygotowaniem projektu najlepiej żeby zajął się UX Designer, czyli osoba specjalizująca się w projektowaniu interfejsu użytkownika. UX Designer powinien ściśle współpracować z właścicielem, który to najlepiej wie jak ma działać dana aplikacja.

Może to nie wydaje się na pierwszy rzut oka oczywiste ale praca nad projektem graficznym jest dużo tańsze niż praca developerów którzy musieliby niepotrzebnie zmieniać funkcjonalności po ich wdrożeniu.

Jak przygotowywać dokumentację techniczną

Aby odpowiedzieć szczegółowo na to pytanie, potrzeba by przygotować oddzielny artykuł. Ja w tej części skupię się bardziej an ogółu tak aby lepiej zrozumieć czym jest taka dokumentacja. Od razu na wstępie chciałbym zaznaczyć, że nie ma na ten dokument jakiegoś wzoru czy opracowania naukowego. W moim przykładzie, który postaram się tutaj opisać, opieram się na swoich doświadczeniach przy tworzeniu takich dokumentacji.

Aby łatwiej poruszać się po dokumentacji warto ją ustrukturyzować (podzielić na rozdziały). Przykładowa struktura może zawierać:

1. Tytuł projektu
2. Opis projektu
3. Określenie wymagań

• językowych
• technicznych
• dotyczącego przewidywanego ruchu
• graficznych
• SEM & SEO

4. Infrastruktura IT
5. Opis funkcjonalny projektu

• opis poszczególnych modułów projektu
• wymagania co do formularzy i ich walidacji
• możliwe funkcje które użytkownik może wykonać w danym module

Jednak zanim zaczniemy opisywać naszą aplikację ja polecam przygotować sobie makiety (można je wykonać ręcznie, ołówkiem lub za pomocą specjalistycznych programów), które w sposób graficzny przedstawią jak nasz aplikacja ma działać. To działanie podobnie jak przygotowanie projektu graficznego przez UX Designera pomoże nam dostrzec pewne luki w logice aplikacji, a także posłuży jako świetna baza do stworzenia profesjonalnego projektu graficznego.

Oczywiście ten punkt dotyczący tworzenia makiet można pominąć, gdy aplikacja jest bardzo mała lub gdy mamy taką wizję, ale ja ze swojego doświadczenie zalecam poświęcenie kilku dodatkowych godzin aby to zrobić.

Na koniec chciałem także przedstawić inne formy przygotowywania dokumentacji technicznej. Możemy sobie wyróżnić:

• dokumentację opisową - tekstowe przedstawienie funkcjonowania aplikacji (może być w strukturze którą zaproponowałem.
  Zaletą takiej dokumentacji jest możliwość jej wykorzystania do opisu poszczególnych zadań dla programistów
• dokumentację opisowo graficzną - jest to połączenie dokumentacji tekstowej i graficznej. Jest to rekomendowana przeze mnie forma dokumentowania aplikacji.
• dokumentację graficzną - przestawienie działania aplikacji w postaci grafik przedstawiających poszczególne stany aplikacji
• dokumentację blokową - jedna z najtańszych i najszybszych do przygotowania jednak z mojego punktu widzenia przynosząca najmniej wymierne korzyści jednak bardzo dobra, jako baza do przygotowania bardziej rozbudowanej dokumentacji.

Dlaczego warto wytwarzać dokumentacje

Poniekąd odpowiedzieliśmy sobie między wierszami na to pytanie. Tutaj jednak postaramy się podsumować to co do tej pory powiedzieliśmy sobie o dokumentacji technicznej z naciskiem dlaczego warto.

Aby szybko odpowiedzieć sobie na to zagadnienie warto zastanowić się czy nasza aplikacja będzie duża i skomplikowana. Jeżeli odpowiedź jest twierdząca to stanowczo powinniśmy podjąć te wysiłki i na pewno ta inwestycja się zwróci w postaci mniejszej ilości poprawek i zmian w funkcjonalności. Jeżeli nasz projekt wydaje się krótki np 1-3 miesiące pracy to można posłużyć się mniej skomplikowaną dokumentacją, np.: graficzną lub blokową.

Wiadomym jest że wytworzeniem takiej dokumentacji będzie wiązać się z jakimś nakładem czasowy a co za tym idzie także nakładem finansowym. Jednak uwierzcie mi, z mojego doświadczenia, te nakłady są kroplą w morzu jeżeli porównamy to z późniejszymi nakładami jakie trzeba ponieść gdy czegoś się do końca nie przemyślało.

Życiowe przypadki gdy projekty nie posiadały dokumentacji.

Na koniec tego artykułu chciałbym was przestrzec przed brakiem dokumentacji technicznej i rozpisanych funkcjonalności na bazie moich doświadczeń oraz doświadczeń moich klientów. Wiadomym jest że przygotowanie dokumentacji oraz projektów, makiet graficznych zabiera sporo czasu, dodatkowo opracowanie całej koncepcji skomplikowanej aplikacji także może zająć sporo czasu. Byłem świadkiem gdy taki proces zajmował rok czasu. Dużo? To oczywiście zależy, w projekcie w którym brałem udział powiedziałbym że dało się to zrobić w 6 miesięcy ale wcale nie uważam że rok czasu przy  bardzo zaawansowanych projektach to dużo.

Przejdźmy teraz do porażek z którymi się w swojej karierze spotkałem. Pierwszą z nich był nasz prywatny projekt marketingowy którego dokumentacja techniczna została napisana na kolanie i gdy doszło do implementacji i coś zaczęło powstawać to okazało się że: 

• po pierwsze to nie wygląda ładnie (brak projektu graficznego),
• po drugie zaczęły pojawiać się logiczne braki podstawowych funkcjach.

Nasza aplikacja wydawała się dość prosta i mała jednak ostatecznie przerwaliśmy pracę i obecnie opracowujemy do niej dokumentację techniczną i projekt graficzny od nowa. Dzięki temu oprogramowanie zyskało dodatkowe funkcjonalności oraz zostało przemyślane biznesowo jako rozwiązanie SaaS.

Kolejną aplikacją w której mieliśmy przyjemność brać udział był system parabankowy który miał opisane pewne ramy i nawet przygotowane projekty graficzne, jednak w połowie prac nad aplikacją zaprzestano analizować kolejne funkcjonalności i przygotowywać odpowiednie projekty i przez to nasza praca posuwała się bardzo wolno i na koniec musieliśmy sporo rzeczy przerobić lub robić od nowa.

Następną lekcję wyciągnąłem z aplikacji wspierającej procesy HR. Jest to bardzo zaawansowana aplikacja która przez kompletny brak dokumentacji technicznej była zmieniana tyle razy że już tego nie sposób spamiętać. Ostatecznie aplikacja ujrzała światło dzienne ale moim skromnym zdaniem dało się ją napisać w 4 lub 5 krotnie mniejszym budżecie.

Myślę że nic tak nie przemawia do przedsiębiorców jak pieniądze. Więc proszę Was zastanówcie się na tym tematem i nie wybierajcie zawsze najszybszej i najtańszej drogi w ramach przetargu, bo może Was to zaprowadzić w poważne kłopoty finansowe.

Mam nadzieje że po przeczytaniu tego artykułu jesteście uzbrojeni w wiedzę, którą będziecie mogli wykorzystać przy podpisywaniu kontraktów i umów na zrobienie oprogramowania dla Waszych firm.