Zespoły produktowe i zespoły programistyczne mają wspólną bolączkę: dokumentację.
Dokumentacja produktu odnosi się do podręczników i przewodników skierowanych do użytkowników, które wyjaśniają przepływ pracy i interfejs użytkownika produktu. W jaki sposób przeciętny użytkownik może produktywnie korzystać z tego produktu? W tym sensie dokumentacja produktu może być stosowana w przypadku oprogramowania.
Dokumentacja oprogramowania odnosi się do podstawowych technologii, warunków wstępnych i konfigurowalnych atrybutów oprogramowania. W jaki sposób administratorzy IT konfigurują, monitorują, hostują i wdrażają oprogramowanie dla użytkowników? Ten rodzaj dokumentacji jest ważny, zwłaszcza gdy do zestawu dodawanych jest wiele wersji lub gałęzi.
W pewnym sensie dokumentacja produktu jest jak uczenie kogoś, jak prowadzić samochód. Kierownica obraca samochód, pedał przyspieszenia przesuwa samochód, pedał hamulca zatrzymuje samochód. Dokumentacja oprogramowania uczy kogoś, jak działa samochód. Koło jest połączone z przednią osią, która obraca przednie opony, aby zmienić tor jazdy; pedał przyspieszenia zwiększa przepływ powietrza do silnika, który zasysa więcej paliwa, generując moment obrotowy i moc.
Oba rodzaje dokumentacji są ważne. Jeden edukuje użytkowników, a drugi administratorów i programistów. Świetnie jest pokazać ludziom, jak prowadzić samochód, ale jeśli nikt nie wie, jak działa samochód, co się stanie, gdy samochód się zepsuje?
Drobne różnice między dokumentacją produktu a dokumentacją oprogramowania
Istnieją drobne różnice, których należy być świadomym w przypadku dokumentacji produktu i oprogramowania:
Dokumentacja oprogramowania i produktu: Docelowi odbiorcy i persona
Dokumentacja produktu skierowana jest do jednego odbiorcy - użytkownika. Zakłada, że użytkownik nie ma wiedzy technicznej, komunikując się prostym językiem angielskim z minimalną ilością żargonu. Podobnie jak w przypadku praktyk technicznych w porównaniu z dyplomem uniwersyteckim, edukuje ludzi, jak robić rzeczy, z mniejszym naciskiem na wiedzę teoretyczną lub koncepcyjną.
Dokumentacja oprogramowania jest skierowana do administratorów IT, inżynierów i programistów. Obejmuje projekt i architekturę oprogramowania, instrukcje konfiguracji wiersza poleceń, wsparcie API i integracji, zarządzanie danymi i raportowanie, topologię sieci - w zasadzie tryby, które sprawiają, że maszyna działa. Dokumenty te tworzą pojedyncze źródło prawdy (SSOT), do którego personel IT może się odwoływać podczas monitorowania i rozwiązywania problemów z aplikacją.
Dokumentacja oprogramowania i produktu: Częstotliwość aktualizacji
Dokumentacja oprogramowania musi być konsekwentnie aktualizowana, gdy nowe zatwierdzenia są łączone z głównym kanałem wydania. Dokumentacja oprogramowania musi podkreślać nowe funkcje i polecenia oraz wycofywać stare funkcje. Nowe lub zmieniające się zależności powinny zostać udokumentowane, a obsługa funkcji na wszystkich platformach docelowych powinna zostać wyjaśniona - na przykład jedna funkcja działa w systemie Windows, ale nie w systemie Linux.
Dokumentacja produktu wymaga aktualizacji tylko wtedy, gdy edycje oprogramowania bazowego powodują zmianę w przepływie pracy lub użyteczności. Deweloper zmienia kod bramki płatności, ale proces płatności dla użytkowników pozostaje taki sam, więc aktualizacje nie są potrzebne.
Pokazuje to naturalną hierarchię dokumentacji oprogramowania. Techniczna dokumentacja oprogramowania tworzy fundament, a późniejsza dokumentacja produktu opiera się na tym fundamencie. Dlatego należy skupić się na tworzeniu doskonałej dokumentacji oprogramowania, ponieważ rodzi ona jeszcze lepszą dokumentację produktu.
Przykładowe ramy formatowania dla dokumentacji produktu i oprogramowania
Dokumentacja produktu może być zgodna z tymi ramami:
-
Nazwa produktu
-
Przegląd przeznaczenia produktu
-
Przewodnik konfiguracji
-
Objaśnienia i obrazy funkcji 1
Funkcja 2 Objaśnienia i obrazy
- Linki do pomocy technicznej dla klientów
Podobnie, dokumentacja oprogramowania może być zgodna z tymi ramami:
-
Nazwa oprogramowania
-
Przegląd przeznaczenia oprogramowania
-
Zależności oprogramowania
Podręcznik instalacji
-
Objaśnienia i obrazy funkcji 1
-
Objaśnienie funkcji 2 i obrazy
-
Linki do pomocy technicznej
Najwyraźniej te dwa typy dokumentacji są ze sobą ściśle powiązane i mają podobną strukturę. Oznacza to, że zespoły produktowe i programistyczne mogą się wiele nauczyć od siebie nawzajem i mają duży potencjał podczas wspólnej pracy nad dokumentacją.
Zespoły ds. dokumentacji produktu i oprogramowania mogą się wzajemnie uzupełniać
Istnieją wyraźne podobieństwa między dokumentacją produktu i oprogramowania. W związku z tym pojawia się pytanie: czy zespoły produktowe i programistyczne mogą ze sobą współpracować?
Tak, mogą i powinny!
Zespoły programistyczne rozumieją żargon techniczny i podstawowe technologie. Zespoły produktowe rozumieją, co użytkownicy widzą, czego chcą i potrzebują; doświadczenie użytkownika. Autorzy dokumentacji oprogramowania mogą dostarczać szczegółowych informacji technicznych, a autorzy dokumentacji produktu mogą rozwodnić szczegóły techniczne, aby mogli z nich korzystać laicy.
Wyobraź sobie, że próbujesz wyjaśnić coś w kategoriach laików, nie mając wysokiego poziomu zrozumienia potrzebnego do sformułowania czegoś, co laik zrozumie. Tak właśnie dzieje się, gdy dokumentacja produktu jest tworzona przed dokumentacją oprogramowania.
Czym jest mechanika kwantowa? Kot Schrodingera to prawdopodobnie pierwsza myśl, jaka przychodzi ci do głowy! Ale co mechanika kwantowa ma wspólnego z kotami? Dla użytkownika nie ma to znaczenia. Dla fizyka oznacza to wszystko.
Zacznij od dokumentacji oprogramowania, skończ na lepszej dokumentacji produktu w Docsie
Podsumowując, istnieje wiele korzyści z używania dokumentacji oprogramowania jako szablonu dla późniejszej dokumentacji produktu. Dokumentacja oprogramowania powinna działać jako jedno źródło prawdy dla personelu IT i autorów dokumentacji produktu. Po jej napisaniu autorzy dokumentacji produktu będą mieli jasność i zrozumienie, aby uprościć i udostępnić klientom wiedzę przyjazną dla użytkownika, z technicznymi wskazówkami dotyczącymi korekty i zapewnienia jakości.
Po prostu, zaczynając od świetnej dokumentacji oprogramowania, autorzy mogą tworzyć jeszcze lepszą dokumentację produktu!
Zacznij tworzyć dokumentację, która pomoże Twoim klientom zrobić więcej. Zapisz się na nasz plan startowy (forever free!) i dostarczaj dokumentację, która zachwyca z Docsie!