Close

Tworzenie lepszej dokumentacji

Właśnie wystartował nowy projekt i musisz dostarczyć dokumentację (wskazówka: $#*&^!%).

Dopada Cię początkowe zniechęcenie? Z pewnością — ale już spieszymy z pomocą! Poniżej znajdziesz dokumentację na temat dokumentacji [(mrugnięcie)] — przewodnik krok po kroku z fachowymi poradami, który ułatwi Ci przeprowadzenie całego procesu.Do dzieła!


Dlaczego to takie ważne?

Najprościej rzecz ujmując, dokumentacja pomaga ludziom wypełniać ich obowiązki. Jednak, jak to bywa w przypadku większości niewytłumaczalnie niezwykłych rzeczy, jej rola znacznie wykracza poza samą pomoc w realizacji zadań. Dokumentacja ułatwia użytkownikom i zespołom:

Oszczędzanie energii umysłowej

Można wykonywać pracę bez nadmiernego zastanawiania się i minimalnym wysiłkiem.

Zapewnianie spójności

Czytelnicy zyskują dostęp tych samych informacji, procesów oraz planów przedstawianych w spójny sposób.

Minimalizowanie obciążenia pracą

Można szybko i sprawnie przeprowadzić onboarding członków zespołu, aby od razu mogli przystąpić do pracy.

Wzmacnianie wizerunku firmy

Podkreślenie opartego na chęci udzielania wsparcia i pomocy stanowiska firmy wobec klientów zewnętrznych i pracowników wewnętrznych.

Jeśli nie zaoferujesz korzyści, nikt nie zwróci na to uwagi. Musisz ukształtować sposób, w jaki czytelnicy będą postrzegać udostępniane przez Ciebie informacje, oraz uzmysłowić im, dlaczego są one istotne.

Czym jest dokumentacja?

Dokumentacja jest dokładnie tym, z czym nam się kojarzy: zbiorem dokumentów. Kompasem dla typowego użytkownika końcowego. Zbiorem porad strategicznych dla tkwiącego w Tobie inżyniera oprogramowania. W środowisku bardziej technicznym dokumentację stanowią zazwyczaj tekst lub ilustracje dołączone do oprogramowania. Te dokumenty służą za przewodnik zawierający informacje o sposobie działania, obsługi i użytkowania oprogramowania. Zespoły pracujące nad oprogramowaniem mogą sięgać do dokumentacji przy omawianiu wymagań dotyczących produktu, informacji o wersji czy specyfikacji projektu. Zespoły techniczne mogą korzystać z dokumentacji w celu szczegółowego opisu kodu i interfejsów API oraz rejestrowania własnych procesów tworzenia oprogramowania. Na poziomie zewnętrznym dokumentacja często przybiera postać instrukcji i przewodników dla administratorów systemów, zespołów wsparcia oraz innych użytkowników końcowych.

Całą dokumentację powinno się tworzyć z myślą o realizacji 2 głównych celów:

1. Informowanie użytkowników

2. Ułatwianie użytkownikom pomyślnej realizacji zadań

Przystępując do pracy nad jakąkolwiek dokumentacją, zacznij od zdefiniowania przedmiotu zainteresowania bądź ogólnego lub szczegółowego celu, aby odbiorcy od samego początku wiedzieli, o czym będą czytać.

Rodzaje dokumentacji

Jak już wcześniej wspomniano, dokumentacja zarówno wewnętrzna, jak i zewnętrzna, może przybierać szereg form. Różne rodzaje dokumentacji wymagają uwzględnienia odmiennego stylu, tonu, formatowania, autorów, odbiorców i treści. Najczęściej spotykane rodzaje dokumentacji:



Dokumentacja wewnętrzna
Dokumentacja zespołu — ilustracja

Dokumentacja zespołu

Dokumentacja zespołu pomaga nakreślić charakter wykonywanych prac, aby członkowie zespołu mogli skutecznie współpracować. Te dokumenty przybierają postać planów projektów, harmonogramów zespołu, raportów o stanie, notatek ze spotkań oraz dowolnych innych form, których zespół może potrzebować, aby funkcjonalnie i efektywnie realizować zadania. Tego rodzaju dokumentacja jest szczegółowa, dzięki czemu wszyscy mają dostęp do tych samych informacji.

Dokumentacja referencyjna — ilustracja

Dokumentacja referencyjna

Dokumentacja referencyjna pełni funkcję firmowych materiałów edukacyjnych dotykających ważnych tematów, procesów i zasad. Może ona zawierać zasady opracowane przez dział HR, procedury prawne związane z zatrudnianiem zewnętrznych dostawców czy samouczki na temat ubiegania się o świadczenia w firmie. Pamiętaj, że dokumentację referencyjną tworzy niewielka grupa ludzi z myślą o dużym i zróżnicowanym gronie odbiorców, dlatego ważne jest, aby zawarte w niej treści były przystępne.

Dokumentacja projektu — ilustracja

Dokumentacja projektu

Dokumentacja projektu jest z zasady związana z konkretnym projektem i zapewnia procesowi opracowywania produktu tak potrzebną strukturę. Obejmuje ona informacje ofertowe, dokumenty wymagań w zakresie produktu, wytyczne dotyczące projektowania lub szkice, harmonogramy oraz inne istotne informacje niezbędne do rozwoju produktu. W jej tworzeniu uczestniczą menedżerowie projektu, inżynierowie, projektanci oraz inne osoby.



DOKUMENTACJA ZEWNĘTRZNA
Dokumentacja systemu — ilustracja

Dokumentacja systemu

Dokumentacja systemu obejmuje szczegółowe informacje o kodzie, interfejsach API oraz innych procesach, które stanowią dla deweloperów i programistów źródło wiedzy o metodach i funkcjach, których można użyć przy tworzeniu konkretnego oprogramowania, a także o ograniczeniach i wymaganiach. Kluczowym elementem tego rodzaju dokumentacji są fragmenty kodu, takie jak wywołania i odpowiedzi interfejsu API.

Dokumentacja użytkownika końcowego — ilustracja

Dokumentacja użytkownika końcowego

Dokumentacja użytkownika często stanowi najbardziej widoczny rodzaj dokumentacji. Powinna być jasna i zrozumiała. Należy ją aktualizować przy każdej publikacji nowej wersji oprogramowania. Może mieć postać plików „Readme”, instrukcji instalacji, przewodników dla administratorów, baz wiedzy na temat produktu czy samouczków (najbardziej pomocnych ze wszystkich). Podobnie jak w przypadku dokumentacji referencyjnej, nad tym rodzajem dokumentacji także pracuje niewielka grupa autorów, a z uwagi na szerokie grono odbiorców jej treść musi być przystępna.

Uwzględnienie przykładów w dokumentacji stanowi ogromną korzyść dla odbiorców. Niezwykle ułatwiają one zrozumienie koncepcji i pomysłów, a czytelnik zyskuje poczucie, że naprawdę wiesz, o czym piszesz.

Tworzenie dokumentacji

Ostatecznym celem jest zapewnienie, aby dokumentacja była przydatna dla czytelnika. Aby ułatwić to zadanie, poniżej przygotowaliśmy sformatowaną w postaci samouczka dokumentację na temat tworzenia dokumentacji.

1. Analiza

Co użytkownicy muszą wiedzieć na temat Twojego produktu, projektu lub interfejsu API? Wykorzystaj narzędzie analityczne, aby sprawdzić, czego szukają, przejrzyj internetowe fora społecznościowe i grupy dyskusyjne, przeprowadź wśród użytkowników badania i testy użyteczności. Upewnij się również, że znasz swój produkt i potrafisz w prosty sposób odpowiedzieć na pytania użytkowników oraz objaśnić nowe funkcje i przepływy pracy.

2. Wprowadzenie

Przedstaw wyraźnie, czego będzie dotyczyła Twoja dokumentacja, i dlaczego zapoznanie się z jej treścią jest ważne dla czytelnika.

3. Szczegóły

Opracuj konspekt i wersję roboczą treści. Zastosuj odpowiedni dla odbiorców styl i ton (bądź człowiekiem, a nie maszyną!), zachowując przy tym spójność i zwięzłość. W czytelny sposób przekaż istotne szczegóły.

4. Format

Uporządkuj swoją stronę, aby można ją było z łatwością prześledzić od początku do końca. Wytnij niepotrzebne treści, a dłuższe fragmenty przeplataj elementami wizualnymi, takimi jak diagramy, zrzuty ekranu i obrazy.

5. Recenzja

Poproś o opinię zwrotną, aby wyeliminować przypadkowe błędy językowe. Upewnij się, że recenzenci znają cel opracowywanej dokumentacji. Ułatwi im to wykrycie mało precyzyjnych sformułowań czy brakujących zagadnień.

6. Publikacja

Po otrzymaniu recenzji i wprowadzeniu zmian możesz wreszcie opublikować dokument! Gdy już to zrobisz, nasłuchuj uważnie wszelkich opinii i komentarzy. Dokumentacji nie można po prostu utworzyć i o niej zapomnieć.

Złote rady

Jak widać, w tworzeniu dokumentacji nie chodzi wyłącznie o poskładanie ze sobą słów i instrukcji. W tym szaleństwie jest metoda, moi drodzy. Pamiętajcie o poniższych zasadach o każdej porze dnia i nocy, a zwłaszcza przy tworzeniu dokumentacji:

Zachowaj zwięzłość

Dokumentacja powinna zawierać tylko tyle informacji, aby można było wykonać zadanie bez tworzenia zgłoszenia o pomoc. Uwzględnij kluczowe kwestie i opcję przejścia do szczegółów, z której mogą skorzystać czytelnicy.

Elementy wizualne to podstawa

Elementy wizualne są kluczem do sukcesu. Projekt produktu, przykłady kodu, demonstracje w środowisku produktu, zrzuty ekranu i samouczki wideo odgrywają ogromną rolę w ułatwianiu czytelnikowi zrozumienia koncepcji, procedury czy istoty zadania. Pamiętaj o układzie, czytelności i podziale na łatwe do przyswojenia fragmenty.

Poznaj swoich odbiorców

Postaw się na miejscu użytkownika. Poznaj swojego czytelnika, przejrzyj środowisko produktu i dokumentację z jego perspektywy. To zawsze powinno stanowić drogowskaz przy wyborze sposobu przekazu i jego treści.

Zacznij z wysokiego C

Najlepsza dokumentacja jest jasna, zwięzła, merytoryczna, a co najważniejsze zapewnia korzyści odbiorcom. Skorzystaj podczas tworzenia dokumentacji z oprogramowania do współpracy zespołowej, takiego jak Confluence, aby skrócić czas poszukiwania informacji i poświęcić go więcej na praktyczne działania.

Dowiedz się więcej