6 Najlepszych przykładów dokumentacji oprogramowania i najlepszych praktyk

Chcesz poznać sukces dobrych, dobrze prosperujących oprogramowania?

To ich dokumentacja.

Dobre firmy dużo inwestują w dokumentację oprogramowania. W rzeczywistości pierwszą rzeczą, jaką robią, jest stworzenie dokumentacji, która obejmuje cel, zakres, zakres, jego referencje w zakresie pracy i branży.

Umożliwia to interesariuszom zaglądanie kosztów rozwoju oprogramowania, harmonogramu, kątu marketingu i strategii, luki w funkcjonalności i kluczowych funkcji, na których można się skupić.

Pomaga nie tylko w rozwoju, dokumentacja oprogramowania jest jedną z najczęściej stosowanych metod szkolenia nowych pracowników, wdrażania nowych klientów i zapewniania wsparcia.

Stworzyliśmy również wiele oprogramowania i ich dokumentacji, z czego możemy poprowadzić Cię z dokumentacją oprogramowania .

Więc zacznijmy!

Rygorystycznie testujemy i badamy każdy produkt, który polecamy za pośrednictwem herothemów. Nasz proces przeglądu. Możemy również zdobyć prowizję, jeśli dokonasz zakupu za pośrednictwem naszych linków.

Co to jest dokumentacja oprogramowania?

Dokumentacja oprogramowania to każdy materiał pisemny lub wideo, który pomaga w tworzeniu oprogramowania, rejestruje procesy tworzenia i postępach, wyjaśnia, jak działa aplikacja, kieruje użytkownikami skutecznie używającym oprogramowania i służy jako materiał obsługi klienta.

Rodzaje dokumentacji oprogramowania

Projekt oprogramowania może potrwać kilka dni do kilku lat. Więc przed rozpoczęciem jakiegokolwiek oprogramowania biznesowego ważne jest, aby zrozumieć, w co się nurkujesz.

W rezultacie dokumentacja oprogramowania obejmuje szeroki zakres dokumentacji. Od etapów planowania po przestrzeganie przepisów.

Niektóre dokumenty wyprodukowane w cyklu życia oprogramowania, źródło - cds.cern.ch

Pomoże ci to uzyskać ogólny pomysł, jak rozpocząć dokumentację oprogramowania i rzeczy do omówienia.

1. Dokumentacja projektu

Dokumentacja projektu jest tworzona na początkowych etapach tworzenia oprogramowania i utrzymywana przez cały cykl życia.

Ponieważ daje ptakom widok procesu rozwoju oprogramowania, bardzo pomaga w podejmowaniu decyzji.

Obejmuje badania, testy, pomysły, przykłady, alokacja zasobów, szczegóły spotkania, postęp pracy, kamienie milowe i przyszłe cele.

2. Wymagania i dokumentacja projektowa

Wymagania i dokumentacja projektowa oba robota ręka. To tak, jakby stworzyć szorstki szkic oprogramowania, zanim zaczniesz je kodować.

Zawiera kluczowe elementy, takie jak:

• Przegląd systemu
• Cele i cele na wysokim poziomie
• Wymagania funkcjonalne
• Kryteria akceptacji
• Architektura systemu
• Stos technologii

Chociaż dokumentacja wymagań koncentruje się na tym, co powinien zrobić system, dokumentacja projektowa koncentruje się na sposobu zbudowania systemu.

Najlepsze praktyki: najlepiej wymienić wszystkie swoje wymagania z oprogramowania i podzielić je na kilka etapów. Pomoże to od samego początku zaprojektować lepsze oprogramowanie.

Wiele oprogramowania jest przeprojektowane (np. Przepisane w innym języku lub ponownie ustrukturyzowane) po prostu dlatego, że nie zostało ono odpowiednio zaprojektowane.

3. Dokumentacja techniczna

Dokumentacja techniczna obejmuje sposób budowy, obsługi i utrzymywania systemów oprogramowania.

W dokumentacji oprogramowania musisz utworzyć dokumentację techniczną, aby wyjaśnić:

• Jak działa kod
• API (interfejs programowania aplikacji)
• Schemat bazy danych (tabele, relacje i przepływ danych)
• Jak zaktualizować zależności oprogramowania
• Rozwiązywanie problemów

Mamy pełny przewodnik po tworzeniu i pisaniu dokumentacji technicznej, sprawdź to!

4. Dokumentacja użytkownika

Dokumentacja użytkownika pomaga użytkownikom końcowym (klientom) skutecznie korzystać z oprogramowania.

Obejmuje:

• Instrukcje obsługi : utworzone dla użytkowników końcowych. Na przykład, w jaki sposób użytkownicy mogą korzystać z określonej funkcji Twojego produktu.
• Materiały szkoleniowe: Zawiera różne zasoby szkoleniowe dla użytkowników końcowych. Na przykład przewodniki konfiguracyjne, filmy lub kursy.

Dokumentacja użytkownika różni się nieco od dokumentacji technicznej, mamy kilka przewodników, które pomogą Ci dowiedzieć się więcej o tym:

• 5 Najlepszych przykładów dokumentacji użytkownika (dobre i złe + wskazówki)
• Jak utworzyć instrukcję obsługi: od zera do bohatera (pełny przewodnik)

5. Dokumentacja testowa

Testowanie dokumentacji lub wytycznych specjalnie utworzonych dla zespołów QA (jakość). Aby zapewnić, że jakość oprogramowania spełnia standardy rynkowe lub spełnia wymagania interesariuszy.

Obejmuje:

• Plan testu i przypadki testowe
• Listy kontrolne do śledzenia podczas testowania funkcji oprogramowania
• Wytyczne dotyczące jakości kodu
• Zautomatyzowane testy

6. Dokumentacja konserwacji / bezpieczeństwa

Ten rodzaj dokumentacji pomaga programistom i zespołom w utrzymaniu, aktualizacji, debugowaniu i rozwiązywaniu problemów z oprogramowaniem.

Obejmuje:

• Zaktualizuj wytyczne lub listy kontrolne
• Przewodniki do aktualizacji zależności oprogramowania
• Kontrole dostępu
• Plan incydentu
• Notatki z wydania

7. Dokumentacja prawna i zgodności

Dokumentacja prawna i zgodności w celu zapewnienia, że ​​oprogramowanie jest zgodne z normami prawnymi, regulacyjnymi i branżowymi.

Dokumenty prawne, takie jak:

• Umowa licencyjna użytkownika końcowego (EULA)
• Warunki usług (TOS)
• Polityka prywatności
• Licencje oprogramowania i informacje o użytkowaniu

Dokumenty zgodności, takie jak:

• Zgodność z ochroną danych i prywatności, która obejmuje przepisy takie jak RODO, CCPA lub HIPAA.
• Zgodność bezpieczeństwa
• Zgodność z dostępnością
• Przepisy dotyczące branży

Odkryj : jaka jest dokumentacja oprogramowania?

6 najlepszych przykładów dokumentacji oprogramowania do nauki

1. WordPress

Są szanse, że już wcześniej korzystałeś z WordPress, więc może to być najlepszy przykład dokumentacji oprogramowania do nauki.

WordPress jest używany na 43% wszystkich stron internetowych w Internecie. Tak więc jego dokumentacja musi być jednym z najlepszych, aby służyć milionom ludzi z całego świata.

Obejmuje to programistów, projektantów, blogerów, pisarzy lub każdego, kto chce zbudować stronę internetową.

Główna dokumentacja WordPress jest podzielona na trzy różne sekcje :

1. Naucz się WordPress: zawiera przewodników w postaci dogłębnych kursów, filmów i pisemnych samouczków. Skierowane do początkujących, pośrednich i zaawansowanych użytkowników.
2. Główna dokumentacja: skierowana do normalnych użytkowników. Aby zapewnić przegląd funkcji WordPress, w postaci krótkich prostych pisemnych samouczków.
3. Zasoby programistów: skierowane do programistów, którzy tworzą motywy WordPress, wtyczki lub chcą rozszerzyć WordPress o niestandardowe kodowanie. Obejmuje przewodniki początkowe, dokumentację API i przykłady kodowania.

Ogólnie rzecz biorąc, tworzy idealne centrum zasobów dla każdego, kto chce stworzyć stronę internetową lub zacząć od WordPress. Łatwo jest nawigować, przyjazne wyszukiwanie, dogłębne, pełne przykładów i bardzo przydatne.

Rzeczy do nauczenia się z dokumentacji oprogramowania WordPress:

• Znają ich odbiorców , w rezultacie możesz zobaczyć wiele sekcji dokumentacji i przewodników utworzonych na podstawie poziomu wiedzy użytkowników lub wiedzy specjalistycznej .
• Ciągłe aktualizacje . Dokumentacja oprogramowania nie jest rzeczą jednorazową, funkcje oprogramowania, interfejs użytkownika lub funkcjonalność mogą się zmieniać z czasem. To samo stało się z WordPress (od klasycznego motywu blokowego i dodawania Gutenberga) i starali się zaktualizować swoją dokumentację przy każdej aktualizacji.
• Fora wsparcia . Oprócz premiotowych samouczków i przewodników WordPress zawiera również forum wsparcia dla każdej wtyczki i motyw. Jest to bardzo pomocne, jeśli użytkownicy mają problemy z rozwiązywaniem problemów.
• SEO (przyjazny dla wyszukiwarki) . W mojej 9 -letniej karierze jako użytkownik WordPress rzadko odwiedzałem lub przeglądałem dokumentację WordPress. Wszystko, co zrobiłem, to wyszukiwanie w Google i znalazłem rozwiązanie moich zapytań. Dokumenty WordPress i strony wsparcia generowane przez użytkowników łatwo są indeksowane w Google (lub innych wyszukiwarkach), które pozwalają łatwo je znaleźć.
• FAQ . W dokumentacji nie pomijane są często zadawane pytania. Ale WordPress nie przegapił ich. FAQ dostarczają natychmiastowych informacji lub rozwiązania i są łatwe do skanowania.
• System sprzężenia zwrotnego . Możesz przekazać informacje zwrotne na temat każdego przewodnika, co jest pomocną funkcją znalezienia przestarzałych i nieprzydatnych przewodników.

Co nie lubić w dokumentacji WordPress:

• Brak wielojęzycznej dokumentacji . Chociaż w swoim języku możesz łatwo znaleźć przewodniki WordPress w swoim języku. Ale chciałbym, aby WordPress stworzył kilka samouczków dla popularnych języków.

2. Baza wiedzy Herothemes

Nasza własna dokumentacja oprogramowania.

To nie jest najlepszy przykład, ale biorąc pod uwagę, że większość z was ma podobną sytuację do naszej:

• Nie mam pojęcia, od czego zacząć
• Niski budżet

Może to być dobry przykład do nauki.

Herothemes zapewnia wtyczki obsługi klienta, w tym heroiczną bazę wiedzy, która pozwala użytkownikom tworzyć witryny bazy wiedzy lub dokumentacji bez żadnej wiedzy kodowania, do użytku publicznego i wewnętrznego.

Rzeczy do nauczenia się z dokumentacji Herothemes Przykład:

• Tworzenie tylko niezbędnej dokumentacji i poprawa jej. Herothemes ma bardzo niewiele przewodników, biorąc pod uwagę, że większość docelowych klientów to poziom pośredni (programiści, użytkownicy WordPress), a oprogramowanie jest bardzo proste i proste w użyciu.
• Spis treści (TOC) . Biorąc pod uwagę, że niektóre z tych przewodników zawierają całkowitą instrukcję, TOC pomaga znaleźć niezbędne informacje.
• Zrzuty ekranu . Ponieważ większość z nas nie może oszczędzić dobrego budżetu na dokumentację (zwłaszcza przypisując projektanta do tworzenia wysokiej jakości wizualizacji) od samego początku, dodanie zrzutów ekranu jest znacznie lepsze niż nic nie dodawanie. Jednak wizualizacje stworzone przez projektantów naprawdę nadają charakter premium.
• Dokumentacja obsługi śledzenia biletów .

Jest to jedna z heroicznych funkcji KB Analytics do śledzenia biletów wsparcia pochodzącego z dokumentacji. Bardzo pomocne w znalezieniu nieprzydatnych, przestarzałych treści.

• FAQ . Użytkownicy zadają wiele często zadawanych pytań, takich jak zasady zwrotu pieniędzy lub przyszłe aktualizacje, odpowiadanie im za pośrednictwem dokumentacji pomaga użytkownikom łatwo znaleźć je za pomocą paska wyszukiwania i asystent pomocy AI.
• AI pomocy asystentowi . Podobnie jak w przypadku pasków wyszukiwania, AI Asystent pomaga użytkownikom łatwo znaleźć odpowiedzi na ich zapytania. Jest wyszkolony w zakresie treści dokumentacji, więc odpowiedzi są istotne i pomocne.

Co nie lubić w dokumentacji Herothemes:

Ponieważ Herothemes oferuje wiele rozwiązań oprogramowania, grupowanie treści dokumentacji jest trochę bałaganem .

Mamy kilka przewodników, które pomogą Ci utworzyć witrynę dokumentacyjną w WordPress:

• Jak stworzyć bazę wiedzy WordPress (przewodnik krok po kroku)
• Jak utworzyć wewnętrzną dokumentację

3. Dokumentacja portfela oprogramowania Barn2

Barn2 sprzedaje wiele oprogramowania na podstawie WordPress i WooCommerce, które są używane na ponad 90 000 stron internetowych.

Obsłużenie wielu dokumentacji oprogramowania z jednego portalu może być trudne, ale Barn2 robi to pięknie.

Zdecydowanie powinieneś zajrzeć do przykładu Barn2, jeśli masz wiele produktów.

Rzeczy do nauczenia się z dokumentacji Barn2 Przykład:

Barn2 bardzo starannie stworzył swoją stronę wsparcia. Które można zobaczyć z jego ogólną funkcjonalnością i użytecznością.

Po odwiedzeniu ich strony pomocy technicznej znajdziesz wyraźny pasek wyszukiwania z opcją wyboru określonego produktu .

Często zadawane pytania związane z przedsprzedażą, licencjonowaniem, aktualizacjami i problemami technicznymi. Jest to bardzo wciągające do interakcji i zapewnia szybkie odpowiedzi .

Gdy wyszukiwanie nie zapewnia żadnych wyników, pokazuje sposób na osiągnięcie poparcia człowieka.

Mówienie o głównej dokumentacji oprogramowania:

• Znajdziesz wszystkie ważne przewodniki na górze , a przewodniki są podzielone na różne sekcje w celu łatwej nawigacji.
• Zawiera samouczki pisemne i wideo.
• Wsparcie człowieka jest łatwo dostępne z paskiem bocznym CTA.
• Niestandardowe bloki/projekty notatek, wskazówek, komunikatów ostrzegawczych i fragmentów kodu w celu poprawy zdolności skanowania.

Co nie lubić w dokumentacji Barn2:

• Brak systemu sprzężenia zwrotnego . Chociaż zapewniają bezpośredni dostęp do ludzkiego wsparcia, nie ma sposobu na gromadzenie informacji zwrotnych w czasie rzeczywistym od użytkowników. Co może skutkować przestarzałymi informacjami i samouczkami.

Barn2 używa również heroicznej bazy wiedzy do tworzenia dokumentacji oprogramowania.

4. Podręcznik użytkownika iPhone'a

W dokumentacji użytkownika iPhone'a jest wiele rzeczy, które lubi lubisz (przewodniki oprogramowania iOS).

Jest to fantazyjna dokumentacja oprogramowania z łatwymi do naśladowcami instrukcjami, coś takiego, czego można oczekiwać od Apple.

Rzeczy do nauczenia się z przykładu dokumentacji iPhone'a:

Dokumentacja iPhone'ów wygląda oszałamiająco .

• Układ jednej kolumny
• Dużo białej przestrzeni
• Mały akapit i treść
• Piękne wizualizacje
• Dobre użycie nagłówków, list i dzielników

Większość ich dokumentacji polega na tworzeniu tak oszałamiających i pomocnych przewodników.

Kiedy znajdziesz odpowiedni przewodnik, skanowanie go i zrozumienie, co robić.

Dokumentacja iPhone'a jest specjalnie tworzona w ten sposób, więc każdy może ją łatwo zrozumieć.

Jeśli chcesz utworzyć dokumentację oprogramowania produktowego, zdecydowanie polecam tworzenie przewodników użytkowników podobnych do iPhone'a, jeśli masz trochę budżetu na dokumentację.

Oprócz upiększania dokumentacji, Apple nie zapomniało właściwie użyć SEO . Być konkretnym:

• Tytuł i struktura nagłówka
• Interlinowanie w formie TOC, powiązanych postów, poprzednich i następnych nawigacji

System sprzężenia zwrotnego przewodnika jest niesamowity . Klikasz tak lub nie, a w razie potrzeby również podaj opinię.

System sprzężenia zwrotnego nie brzmi tak fajnie, ale kiedy miliony użytkowników przekazują ci opinię, proste śledzenie tak lub nie jest naprawdę przydatne do sprawdzenia wydajności przewodników (po prostu nie możesz odczytać całej tej opinii, prawda?) .

Apple zapewnia również przewodniki oparte na wersjach oprogramowania (w tym przypadku wersja iOS).

Co nie lubić w dokumentacji iPhone'a:

Dużo pochwaliłem powyższą dokumentację iPhone'a, ale jest też kilka irytujących rzeczy.

Zwłaszcza część nawigacji.

• Spis treści nie jest przydatny, ponieważ zawiera wszystkie linki przewodników.
• Ikona wyszukiwania jest zbyt mała, aby ją zauważyć.

5. Dokument projektowania oprogramowania (przykład wewnętrzny)

Dokumentacja oprogramowania rozpoczyna się od samego pomysłu tworzenia dowolnego oprogramowania.

Na przykład początkowa dokumentacja oprogramowania może obejmować:

• Jakie są potrzeby oprogramowania
• Zakres
• Jak to zadziała
• Odniesienia

Posiadanie szczegółowych informacji pomoże uniknąć wielu przyszłych spotkań, przeszkolić nowych pracowników i tworzyć konkretne wytyczne.

Możesz się wiele nauczyć z dokumentu projektowania oprogramowania Doradu Advisor.

Przedstawia wszystkie wymagania potrzebne do rozpoczęcia budowania oprogramowania (w tym przypadku aplikacji internetowej) lub pomocy nowym pracownikom w zrozumieniu wymagań oprogramowania.

Ponadto zawsze możesz to ulepszyć podczas tworzenia oprogramowania.

Rzeczy do nauczenia się z tego przykładu:

• Zawiera podstawowe, ale ważne informacje, takie jak cel, zakres i definicje, które tworzą konkretne wytyczne.
• Zastosowanie diagramów i grafiki wizualnej , aby pomóc programistom lepiej zrozumieć wymagania. Na przykład: opisanie połączeń lub przepływ funkcjonalności ze schematami.

6. Dokumentacja Google

Kto nie zna Google? Każdego dnia używamy ich oprogramowania najwyższej klasy, takich jak Chrome, Gmail, Mapy Google, Dysk Google lub YouTube.

Są one dostępne zarówno dla urządzeń komputerowych, jak i mobilnych. Różne system systemu operacyjnego, urządzeń, rozdzielczości i ustawień.

W takiej sytuacji musi to być koszmar , aby stworzyć coś dobrego bez bałaganu. A Google wykonuje naprawdę dobrą robotę z ich dokumentacją .

Rzeczy do nauczenia się z dokumentacji oprogramowania Google:

• Świetne wykorzystanie kart i akordeonu w celu uproszczenia klastrów treści.

Jeśli tworzysz oprogramowanie dla wielu urządzeń, w ten sposób możesz uniknąć tworzenia wielu dokumentów.

• Niesamowity system sprzężenia zwrotnego. Podobnie jak niektóre z powyższych przykładów, Google zawiera również system sprzężenia zwrotnego tak/nie, który gromadzi również opinie od użytkowników.

Ale Google idzie o krok dalej. Mają system, który zbiera informacje zwrotne na podstawie określonych sekcji . Co jest bardzo intuicyjne i przydatne.

• Szybka treść . Idź tam, kliknij to, pobierz, zainstaluj i boom. Tak czują się szybkie samouczki dokumentacji Google.
• Najlepsze paski do szybkiego dostępu do wyszukiwania, pomocy centrum, społeczności i strony produktu.
• Dokumentacja dostępna w wielu językach .

Co nie lubić w dokumentacji Google:

Próbowałem znaleźć tutaj wiele, na które można narzekać, ale ostatecznie nie mogłem tego zrobić. Google z pewnością ma dobrą dokumentację oprogramowania.

Ostateczne myśli

Omówiliśmy wiele różnych przykładów w tym przewodniku przykładów dokumentacji oprogramowania, a także udostępniliśmy nasze osobiste doświadczenie.

Oto kilka ostatnich słów:

1. Kiedy zaczynasz od tworzenia oprogramowania , stwórz kilka wewnętrznych przewodników, które przedstawiają cel, zakres, zakres, funkcjonalność i kryteria wydania.
2. Zbuduj swoje portfolio dokumentacji podczas tworzenia oprogramowania . Na przykład dokumentacja API i dokumentacja techniczna.
3. Przed uruchomieniem oprogramowania utwórz dokumentację użytkownika, która obejmuje przewodniki konfiguracyjne, przypadki użycia, przegląd funkcjonalności i często zadawane pytania.
4. Po uruchomieniu utwórz samouczki, aby rozwiązać najczęstsze problemy użytkownika i poprawić swoją starą dokumentację.

Dokumentacja to nie żart; Może uratować Cię przed przerażającą przebudową oprogramowania lub procesów przeprojektowania. Mogę pomóc Ci zaoferować lepszą obsługę klienta i zatrzymać klientów.

Jeśli szukasz rozwiązania do dokumentacji oprogramowania , heroiczna baza wiedzy ma wszystko do zaoferowania, które omówiliśmy w tym przewodniku.

Spróbuj!