Praca analityka biznesowego wiąże się z koniecznością zarządzania zarówno mniej, jak i bardziej skomplikowanymi projektami. Niektóre z nich są nowe, a inne trwają już od wielu lat. Aby więc efektywniej realizować przedsięwzięcie od strony produkcyjnej i biznesowej, potrzebna jest prawidłowo wykonana dokumentacja techniczna.
Razem z naszym ekspertem – Wojciechem Kordasem, Senior Business Analyst w SNI Consulting, stworzyliśmy krótki poradnik o tym, jak stworzyć efektywną dokumentację techniczną, tak aby niosła realną wiedzą i była przydatna dla zespołu.
Do czego służy dokumentacja techniczna?
Zanim przejdziemy do konkretnych wskazówek dotyczących tworzenia dokumentacji, warto odpowiedzieć sobie na pytanie, dlaczego właściwie tego typu dokument jest ważny i po co się go tworzy?
Dokumentacja ma opisywać techniczne działanie oraz parametry, które w późniejszym etapie pozwalają na wdrożenie produktu końcowego. W praktyce oznacza to, że w dokumencie muszą znaleźć się opisy mechanik, przykłady zastosowań oraz wszelkie inne dane, mające wpływ na użytkowanie danego produktu.
W przypadku dokumentacji technicznej dotyczącej projektów IT często mamy do czynienia z obszernymi bazami informacji, które są przydatne zarówno dla strony biznesowej, jak i produkcyjnej całego przedsięwzięcia. Aby jednak dokumentacja była przydatna, trzeba ją tworzyć zgodnie z ogólnie przyjętymi zasadami.
Prowadzenie dokumentacji technicznej jest również niezwykle istotne w kontekście uniezależnienia się od „wiedzy plemiennej” niektórych członków zespołu. Bywa bowiem, że przy trwających długo projektach, nieliczni pracownicy pamiętają jeszcze, co było na początku. W sytuacji, gdy pójdą na urlop lub odejdą z projektu, cała praca stoi, ponieważ trzeba znaleźć sposób na uzyskanie trudno dostępnych informacji. Jeśli jednak dokumentacja techniczna od samego początku jest prowadzona rzetelnie i poprawnie, tego typu problem nie występuje. Wszystko znajduje się w bazie i w każdej chwili można do niej sięgnąć, aby uzyskać potrzebne dane.
Co powinna zawierać dokumentacja techniczna?
- Opis rozwiązania konstrukcyjnego
- Charakterystykę materiałową
- Informacje o właściwościach użytkowych produktu
- Jasno określone warunki zastosowania realizowanego projektu
Jak napisać dobrą dokumentację techniczną?
Skoro wiemy już, czym jest i dlaczego tworzy się dokumentację techniczną, czas przejść do kilku ważnych kwestii, które sprawiają, że dokument jest przydatny i realizuje swoje zadania. Poniżej znajdziesz wymagania, niezbędne do przygotowania przydatnej dokumentacji technicznej. Opisane zasady obowiązują bez względu na branżę, w jakiej funkcjonujesz.
#1. Prostota
Bardzo ważna przy tworzeniu dokumentacji technicznej jest świadomość, że dokument będzie wykorzystywany zarówno przez zespół techniczny, jak i stronę biznesową projektu. Oznacza to więc, że żargon charakterystyczny dla danej branży, terminy oraz opis skomplikowanych mechanik muszą być opisane tak, aby zrozumiały je wszystkie osoby zaangażowane w projekt.
#2. Zwięzłość
Zadaniem dokumentacji technicznej jest dostarczenie konkretnych informacji. W większości przypadków ani członkowie zespołu technicznego, ani interesariusze nie mają czasu na wertowanie obszernej dokumentacji, aby znaleźć odpowiedź na swoje pytania. Zwięzłość nie oznacza jednak pomijania ważnych elementów projektu. Dokumentacja nie jest formą literacką a dokumentem czysto funkcjonalnym. Wszystko, co się w niej znajduje, musi być opisane w możliwie najkrótszy i najmniej skomplikowany sposób.
#3. Możliwość nawigacji
Dokumentacja techniczna w przypadku projektów, które trwają już jakiś czas, może przybierać bardzo obszerną formę. Niezwykle ważne jest zatem umożliwienie użytkownikowi przemyślanej nawigacji w celu łatwego odnalezienia potrzebnych danych.
Najskuteczniejszym sposobem na zapewnienie odpowiedniej struktury i hierarchii jest tworzenie dokumentacji z jasno określonymi sekcjami, artykułami oraz odnośnikami do najważniejszych zagadnień. Dzięki takiej budowie nawet przy obszernych dokumentach możliwe jest szybkie uzyskiwanie informacji bez konieczności wertowania kilkudziesięciu lub kilkuset stron.
#4. Konsekwencja
Dokumentacja techniczna „żyje” – oznacza to, że wraz z postępami prac nad danym projektem dokument musi być rozszerzany o nowe informacje. Ważne jednak jest to, aby nie dublować opisów ekranów, wyjaśnień mechanik i definicji używanych terminów. Dobrą praktykę stanowi opisywanie wszystkiego jeden raz oraz stosowanie przemyślanego systemu odnośników. Dzięki temu użytkownik w razie potrzeby szybko dotrze do wyjaśnienia konkretnej kwestii.
Dlaczego nie powinno się dublować treści?
Ryzyko związane z kilkukrotnym opisywaniem tego samego elementu polega na tym, że dokumentację techniczną często na przestrzeni lat tworzą różne osoby. Gdyby każda opisywała swoimi słowami te same terminy lub mechaniki, mogłoby dojść do braku konsekwencji, wprowadzającej w błąd zespół techniczny lub interesariuszy. Dodatkowo, jeśli dana funkcjonalność jest opisana więcej niż raz, to przy każdej zmianie, trzeba aktualizować wszystkie miejsca, w której jest wspomniana. Trzymaj się więc raz użytych definicji i unikaj dublowania treści dokumentu.
#5. Elementy graficzne
Osoby, które tworzą dokumentację techniczną, często mierzą się z zadaniem polegającym na opowiedzeniu o skomplikowanych zagadnieniach w przystępny sposób. Bywa, że nie jest to takie proste, mając do dyspozycji jedynie słowa. O wiele bardziej trafiające do świadomości użytkowników są makiety, mapy procesów lub zrzuty ekranów opisujące daną funkcjonalność. Elementy graficzne są również pomocą dla twórcy dokumentacji, który nie musi już głowić się, jak przedstawić techniczne aspekty w przystępny i zrozumiały sposób.
#6. Wersjonowanie zmian
W momencie, w którym funkcjonalność opisana w dokumentacji technicznej trafi do implementacji, analityk może już zaczynać wprowadzać kolejną wersję. Aby więc uzyskać kontrolę nad tym, co już jest wdrożone, a czym zespół techniczny dopiero się zajmie, warto korzystać z narzędzi oferujących wersjonowanie. Dzięki temu użytkownik łatwo będzie mógł sprawdzić etapy wdrażanych zmian oraz to, czy dana wersja ma akceptację strony biznesowej projektu.
#7. Ewolucja, nie rewolucja
Może zdarzyć się tak, że trafisz do projektu, który trwa już od dłuższego czasu. W takich sytuacjach dokumentacja techniczna w jakiejś formie zapewne już istnieje. Czy zatem, jeśli dotychczas nie była ona prowadzona w taki sposób, w jaki byś tego chciał, należy całkowicie przerobić dokument? W żadnym wypadku! Takie podejście może wprowadzić do projektu chaos wynikający z ingerencji w przyzwyczajenia dłużej pracujących specjalistów. O wiele lepsze są małe usprawnienia oraz wprowadzanie struktury i hierarchii. Dzięki temu zarówno „starsi” pracownicy, jak i osoby, które dopiero dołączają do projektu, będą mogli efektywnie korzystać z dokumentacji.
Dokumentacja techniczna, czyli sztuka porządkowania danych
Tworzenie dokumentacji technicznej powinno odbywać się zgodnie z zasadami oraz dobrymi praktykami pracy. Struktura, odnośniki, prosty język oraz konsekwencja pozwalają na uzyskanie dokumentu, który jest użyteczny i daje możliwość wglądu w zmiany zachodzące w projekcie. Pamiętaj o naszych wskazówkach podczas pracy, a tworzenie dokumentacji technicznej będzie o wiele łatwiejsze.
Chcesz otrzymać podsumowanie artykułów?
