Sprawdź, kto i jak tworzy dobrą dokumentację techniczną w PSI
25.11.2019 - Praca w PSI, Zarządzanie projektami IT
Nasz zespół R&D tworzy platformę technologiczną na użytek programistów pracujących na całym świecie. Zbudowanie funkcjonalnej, przejrzystej i atrakcyjnej bazy wiedzy dotyczącej tego narzędzia wymagało czasu. Sprawdź, jak tworzona jest dokumentacja techniczna PJF (PSI Java Framework) oraz kto za to odpowiada.
Haniu, pracujesz w PSI od 1,5 roku, zajmując się dokumentacją techniczną, dotyczącą naszej platformy technologicznej PSI Java Framework.
Co jest największym wyzwaniem w tworzeniu dokumentacji dotyczącej naszego frameworka?
Hania Nowicka: Wyzwania, przed którymi teraz stoję różnią się od tych z początku mojej pracy w PSI.
Kiedy zaczynałam, dokumentacja była w różnych miejscach (SVN, Wiki koncernowe, archiwa pracowników), w różnym stanie a wytyczne odnośnie standardów były traktowane dość luźno. Krokiem milowym była weryfikacja i uporządkowanie dostępnych źródeł oraz udostępnienie materiałów na docelowej platformie. Nie było to zwykłe kopiuj-wklej, ponieważ dokumenty były tworzone przez różne osoby i różniły się między sobą. Musiałam przyjąć m.in. spójną stylistykę, nazewnictwo, itd.
Teraz najważniejsze materiały są już w jednej przestrzeni, na Confluence, i tutaj dodaję nowe strony, dbając o spójność całej dokumentacji. Wraz z rozwojem firmy coraz więcej deweloperów korzysta z materiałów – pracownicy z różnym doświadczeniem i oczekiwaniami przesyłają swój feedback, na który muszę reagować. Dokumentacja ewoluuje razem z frameworkiem.
Tworzysz dokumentację techniczną na użytek innych programistów, więc standard przygotowanych przez Ciebie dokumentów ma kluczowe znaczenie. Na co szczególnie musisz zwracać uwagę pisząc instrukcje od programisty dla programisty?
Według mnie dokumentacja powinna spełniać kilka kluczowych założeń. Przede wszystkim być aktualna :). Dalej, istotna jest łatwość znalezienia informacji, krótko mówiąc searchable&skimmable. Objaśniające tytuły stron, podział na sekcje z nagłówkami, odnośniki do innych stron – to wszystko ułatwia programistom korzystanie z przygotowanych materiałów.
Jakie narzędzia pomagają Ci w tworzeniu dokumentacji? Czy korzystasz z dodatkowych pomocy, źródeł informacji?
Głównym „nośnikiem” naszej dokumentacji jest Confluence. Daje on dużo możliwości w przedstawianiu materiałów: tworzenie grafik, dodawanie multimediów, wbudowane widgety do formatowania tekstu. Jest to produkt Atlassiana więc ma rozbudowaną bazę wiedzy, z której co jakiś czas korzystam. Filmy montuję w Camtasia Studio, który jest bardzo intuicyjny.
Na samym początku mojej pracy rozmawiałam z grupą naszych deweloperów, którzy podali mi swoje „ulubione” dokumentacje, m.in. dokumentację Springa i Crystal Reports. Takie profesjonalne, rozwijane od lat dokumentacje są doskonałym źródłem know-how. Cały czas szukam „inspiracji” w innych dokumentacjach i blogach tematycznych.
Czego nauczyłaś się podczas pracy w PSI?
W ciągu półtora roku pracy w PSI przede wszystkim opanowałam Confluenca z poziomu zero do biegłego. Przed PSI nie miałam styczności z Javą, więc przeszłam przyspieszony kurs korzystania z Mavena i Eclipsa. Z umiejętności miękkich wyrobiłam sobie odporność na różne próby odkładania tematów :) Wiadomo, że najpierw musi powstać kod, ale ja muszę drążyć temat dokumentacji do niego tak długo, aż nie dostanę potrzebnych odpowiedzi od kierowników projektów i developerów.
Co najbardziej lubisz w swojej pracy?
W PSI mam samodzielne stanowisko, które wymaga bliskiej współpracy z innymi. Jest to dla mnie idealne połączenie, ponieważ dużo decyzji podejmuję samodzielnie, ale nie tracę kontaktu z działem R&D. Są okresy, kiedy przed dłuższy czas pracuję nad dokumentacją do jednego komponentu i są dni, kiedy w ciągu kilku godzin nagrywam filmik, aktualizuję strony i jeszcze analizuję materiały dotyczące nowych wydań. Zdecydowanie pasuje mi brak rutyny.
Najbardziej dumna jestem, najkrócej mówiąc, z dokumentacji :) W ograniczonym czasie utworzyłam od zera rozbudowaną przestrzeń z licznymi materiałami i multimediami, która podawana jest jako dobry przykład wykorzystania Confluence w naszej firmie.
Jak wygląda współpraca z naszymi programistami? Czy zdarzały się sytuacje, które szczególnie zapadły Ci w pamięć?
Atmosfera w dziale to duży plus mojej pracy. Wszyscy są mili i coraz rzadziej słyszę narzekania, że dokumentacja to „zło konieczne” i nikt nie chce jej pisać :) Ze względu na ilość osób zatrudnionych w firmie, czasem nie wszyscy wiedzą, co właściwie robię. Pamiętam sytuację, jak jeden z developerów utworzył stronę opisującą nową funkcjonalność, a ja ją przeredagowałam, sformatowałam, itp. Na następny dzień kolega powiedział, że nie poznał swojej strony i nie miał pojęcia, że dokumentacja może tak wyglądać. Właśnie takie uwagi, doceniające mój wkład, są highlightem mojego stanowiska.
Co robisz, aby urozmaicić sobie pracę, lub nie popaść w monotonię podczas pisania kolejnych stron o zbliżonej tematyce?
Framework jest na tyle zróżnicowany, że ciężko o monotonię. Przeważnie pracuję słuchając Spotify, ale nie mam żadnego algorytmu do wyboru playlisty. Dobrym przerywnikiem są zawsze rozmowy w kuchni czy na korytarzu, a w pokoju prowadzimy mały klub kąśliwych uwag, który rozbudza skuteczniej od kawy.
