Co to jest dokumentacja oprogramowania? Rodzaje i najlepsze praktyki na początek

Jeśli chcesz, aby programiści i użytkownicy końcowi czerpali jak najwięcej korzyści z Twojego oprogramowania, musisz stworzyć wysokiej jakości dokumentację oprogramowania.

Ale czym tak naprawdę jest dokumentacja oprogramowania i jak możesz ją stworzyć dla swojego projektu?

W tym poście omówimy wszystko, co musisz wiedzieć o dokumentacji oprogramowania, w tym:

• Co to jest dokumentacja oprogramowania?
• Różne typy dokumentacji oprogramowania (z przykładami)
• Jak publikować dokumentację oprogramowania (najlepsze narzędzia)
• Niektóre najlepsze praktyki tworzenia dokumentacji oprogramowania wysokiej jakości

Zakopmy się!

Co to jest dokumentacja oprogramowania?

Dokumentacja oprogramowania to treść, która pomaga użytkownikom końcowym, programistom i/lub pracownikom zrozumieć oprogramowanie i używać go do skutecznego osiągania swoich celów.

Zwykle publikujesz dokumentację oprogramowania w swojej witrynie. Ludzie mogą uzyskać do niego dostęp, aby dowiedzieć się więcej o twoim oprogramowaniu i jego działaniu.

W ramach tej szerokiej definicji dokumentacji oprogramowania istnieją różne rodzaje dokumentacji oprogramowania. Porozmawiajmy o tym dalej.

Różne typy dokumentacji oprogramowania

Różne typy dokumentacji oprogramowania można z grubsza podzielić na kilka ogólnych kategorii.

Pierwszą kwestią jest to, dla jakiego rodzaju osoby dokumentacja jest przeznaczona:

• Dokumentacja użytkownika – jest to dokumentacja, którą stworzyłeś dla końcowego użytkownika produktu. Pomaga im zrozumieć, jak korzystać z twojego oprogramowania z perspektywy zwykłego użytkownika, który może mieć lub nie mieć specjalnej wiedzy technicznej.
• Dokumentacja dla programistów – jest to bardziej techniczna dokumentacja oprogramowania, którą stworzyłeś dla programistów, na przykład dokumentacja interfejsu API.

Drugą kwestią jest to, czy dokumentacja jest przeznaczona dla odbiorców zewnętrznych czy wewnętrznych:

• Zewnętrzna dokumentacja oprogramowania — jest to publicznie dostępna dokumentacja, którą utworzyłeś, aby pomóc swoim użytkownikom.
• Wewnętrzna dokumentacja oprogramowania – to prywatna dokumentacja, którą stworzyłeś dla swoich pracowników, aby pomóc im pracować wydajniej i zrozumieć kluczowe szczegóły.

Na przykład możesz mieć jeden zestaw dokumentacji dla programistów dla swoich wewnętrznych zespołów, aby pomóc w pracy nad oprogramowaniem, i inny zestaw publicznie dostępnej dokumentacji dla programistów dla zewnętrznych programistów.

Rozłóżmy bardziej szczegółowo tego typu dokumentację oprogramowania…

Przykłady dokumentacji oprogramowania dla dokumentacji programisty

• Dokumentacja interfejsu API — pokaż programistom, jak wchodzić w interakcje z interfejsem API oprogramowania.
• Readme — przedstaw swoje oprogramowanie i wyjaśnij, do czego służy — zazwyczaj jest to pierwsza rzecz, którą ludzie czytają.
• Informacje o wersji — dokumentuj nowe wersje swojego oprogramowania, w tym wszelkie ważne zmiany.
• Dokumentacja architektury – pokaż strukturę swojego oprogramowania, potencjalnie zawierającą diagramy.
• Dokumentacja modelu danych — udokumentuj różne struktury danych w swoim oprogramowaniu, w tym relacje między różnymi strukturami danych.
• Dokumentacja procesu — dokumentuj kluczowe procesy, takie jak raporty o błędach, mapy drogowe, zapewnianie jakości, protokoły testowania i tak dalej.

Prawdziwy przykład dokumentacji oprogramowania dla programistów można znaleźć w dokumentacji „Developers” Gravity Forms, która obejmuje różne tematy, takie jak:

• Haki PHP (dla WordPressa)
• Obiekty danych
• API PHP
• Baza danych
• REST API

Na przykład, oto jak wygląda dokumentacja REST API:

Przykłady dokumentacji oprogramowania dla dokumentacji użytkownika

• Przewodnik dla początkujących — pokaż użytkownikom, jak szybko rozpocząć pracę z oprogramowaniem.
• Samouczki dotyczące konkretnych przypadków użycia – bardziej szczegółowe samouczki dotyczące wykonywania określonych zadań.
• Glosariusze terminów/instrukcje referencyjne — pomagają użytkownikom zrozumieć kluczowe terminy i szczegóły.
• FAQ – odpowiedz na najczęściej zadawane pytania.

Aby zobaczyć prawdziwy przykład tego, jak mogłaby wyglądać bardziej skoncentrowana na użytkowniku dokumentacja oprogramowania, możesz przejść do tego samego przykładu Gravity Forms z powyższego.

Jeśli spojrzysz na bardziej skoncentrowane na użytkowniku artykuły Gravity Forms, zobaczysz wiele samouczków krok po kroku, jak wykonywać zadania za pomocą interfejsu oprogramowania, wraz ze słowniczkami i objaśnieniami kluczowych funkcji.

W porównaniu z dokumentacją oprogramowania dla programistów zobaczysz więcej zrzutów ekranu i wyjaśnień prostym językiem oraz znacznie mniej bloków kodu.

Jak publikować dokumentację oprogramowania: trzy najlepsze narzędzia do dokumentacji oprogramowania

Aby opublikować dokumentację oprogramowania na swojej stronie internetowej, będziesz potrzebować dedykowanego narzędzia do dokumentacji oprogramowania lub pewnego rodzaju systemu zarządzania wiedzą.

W tej sekcji szybko omówimy niektóre z najlepszych narzędzi do dokumentacji oprogramowania. Następnie w następnej sekcji omówimy najlepsze praktyki tworzenia dokumentacji jakości.

Jeśli chcesz dokładniej przyjrzeć się tutaj, możesz przeczytać nasze pełne przewodniki na temat najlepszych narzędzi do dokumentacji i najlepszego oprogramowania do dokumentacji technicznej.

Heroiczna baza wiedzy

Heroic Knowledge Base to wtyczka dokumentacji i bazy wiedzy dla popularnego oprogramowania WordPress typu open source.

Dzięki Heroic Knowledge Base możesz samodzielnie hostować swoją dokumentację i zachować pełną kontrolę, a jednocześnie mieć dostęp do wszystkich funkcji potrzebnych do tworzenia efektywnej dokumentacji oprogramowania.

Oto niektóre z podstawowych funkcji dostępnych w Heroic Knowledge Base:

• Elastyczny edytor treści , w tym wbudowane bloki objaśnień i innych ważnych szczegółów dotyczących stylu.
• Automatyczny spis treści, dzięki któremu użytkownicy mogą szybko zobaczyć, jaka treść jest omówiona w artykule z dokumentacją i przejść do określonych sekcji.
• Kontrola wersji i historia wersji za pośrednictwem natywnego systemu wersji WordPress.
• Funkcje odkrywania treści, w tym wyszukiwanie Ajax w czasie rzeczywistym z sugestiami na żywo, kategoriami i nie tylko.
• System opinii użytkowników , który pozwala ludziom oceniać artykuły jako pomocne lub nieprzydatne i dzielić się opiniami.
• Analityka wyszukiwania, dzięki której możesz zobaczyć, czego szukają użytkownicy, a także wyszukiwane hasła, które nie zwracają żadnych wyników.
• Widżet natychmiastowych odpowiedzi umożliwiający użytkownikom wyszukiwanie i dostęp do dokumentacji oprogramowania z dowolnego miejsca w Twojej witrynie.

Ponieważ zarówno Heroic Knowledge Base, jak i WordPress są zarówno hostowane samodzielnie, jak i open source, możesz dowolnie modyfikować swoją konfigurację w razie potrzeby.

Możesz udostępnić go publicznie lub ograniczyć dostęp do dokumentacji za pomocą różnych taktyk, takich jak hasła, konta użytkowników, adresy IP, intranet i inne.

Heroic Knowledge Base zaczyna się już od 149 USD rocznie.

Przeczytaj dokumenty

Przeczytaj dokumenty to narzędzie dokumentacyjne, które pomaga w tworzeniu dokumentacji programistycznej.

Jeśli szczególnie koncentrujesz się na tworzeniu dokumentacji technicznej dla programistów, może to być kolejna dobra opcja do rozważenia.

Możesz zarządzać swoją zawartością i historią zmian za pomocą Git, a następnie wdrażać swoje dokumenty w interfejsie użytkownika.

Oto kilka innych godnych uwagi funkcji w Read the Docs:

• Wbudowane narzędzia analityczne , aby zobaczyć, co czytają i szukają Twoi użytkownicy.
• Obsługuje wiele jednoczesnych kompilacji , co może być pomocne, jeśli oferujesz wiele wersji swojego oprogramowania – np. jeden zestaw dokumentacji dla wersji 1.0, a drugi dla wersji 2.0.
• Eksportuj dokumentację w różnych formatach, w tym PDF, HTML i epub.
• Sugestie wyszukiwania na żywo , aby pomóc użytkownikom znaleźć dokumenty.

Read the Docs jest darmowy, jeśli masz projekt oprogramowania typu open source.

W przypadku oprogramowania komercyjnego dostępna jest płatna usługa Przeczytaj dokumenty dla firm, której ceny zaczynają się od 50 USD miesięcznie.

GitBook

GitBook to kolejne narzędzie do dokumentacji oprogramowania technicznego, które pozwala zarządzać dokumentacją za pomocą Git, z obsługą zarówno repozytoriów GitHub, jak i GitLab.

Lub, jeśli nie chcesz używać Git, GitBook pozwala również tworzyć dokumentację za pomocą edytora tekstu lub importować ją z plików markdown lub .doc.

Oto kilka innych godnych uwagi funkcji oferowanych przez GitBook:

• Kontrola wersji w celu śledzenia wersji i historii wersji.
• Edycja zespołowa na żywo , która jest pomocna, jeśli chcesz, aby wielu autorów współpracowało nad artykułami.
• Organizuj artykuły za pomocą „przestrzeni” i „kolekcji” – każda przestrzeń może zawierać wiele kolekcji.
• Opcja eksportu PDF , dzięki której użytkownicy mogą łatwo eksportować dokumentację jako plik do pobrania w formacie PDF.

GitBook jest bezpłatny dla projektów non-profit lub open source.

W przypadku komercyjnych projektów oprogramowania GitBook zaczyna się od 8 USD za użytkownika miesięcznie, przy co najmniej 5 użytkownikach. Oznacza to, że najtańsza miesięczna stawka wynosi 40 USD miesięcznie.

Najlepsze praktyki tworzenia dokumentacji oprogramowania

Na zakończenie przyjrzyjmy się najlepszym praktykom dotyczącym dokumentacji oprogramowania, które pomogą Ci stworzyć efektywną dokumentację.

Pomyśl o celach i potrzebach użytkowników

Podczas pisania artykułu z dokumentacją oprogramowania ważne jest, aby zacząć od odpowiedzi na kilka podstawowych pytań:

• Kim jest użytkownik, dla którego piszesz?
• Co użytkownik próbuje osiągnąć?
• Jaki poziom wiedzy technicznej posiada użytkownik?

Znajomość odpowiedzi na te pytania pomoże Ci zrozumieć, jakie treści omówić i jak ułożyć artykuł w najbardziej optymalny sposób.

Załóżmy na przykład, że oferujesz oprogramowanie do planowania w mediach społecznościowych i piszesz artykuł, który pomaga menedżerom mediów społecznościowych zaplanować pierwszy post w mediach społecznościowych.

Pisząc dokumentację oprogramowania, chciałbyś skupić się na pokazaniu najprostszej drogi dla zwykłego użytkownika końcowego, aby osiągnąć ten cel.

Jeśli oferujesz również interfejs API umożliwiający programistom konfigurowanie własnych integracji, prawdopodobnie chciałbyś omówić to w innym artykule ( chociaż możesz wspomnieć o tej metodzie i podać link do niej ).

Włącz dokumentację oprogramowania do procesu programowania

Podczas tworzenia dokumentacji oprogramowania łatwo wpaść w pułapkę czekania, aż projekt zostanie ukończony, aby go udokumentować.

Może to jednak szybko doprowadzić do zadłużenia dokumentacji, ponieważ możesz dostarczać nowe funkcje lub zmiany, zanim zostaną one udokumentowane.

Aby tego uniknąć, spraw, aby dokumentacja oprogramowania była świadomą częścią cyklu tworzenia oprogramowania. Jeśli nowa funkcja lub produkt nie został jeszcze udokumentowany, nie jest gotowy do wysłania, nawet jeśli sam kod jest gotowy.

Uczyniwszy dokumentację podstawowym wymogiem procesu tworzenia oprogramowania, możesz mieć pewność, że wszystkiemu wysyłanemu towarowi towarzyszy odpowiednia dokumentacja.

Używaj spójnego formatowania i stylu

Aby pomóc ludziom efektywniej pracować z dokumentacją oprogramowania, ważne jest stosowanie spójnego formatowania i stylu we wszystkich dokumentach.

Korzystanie z tego samego formatowania pozwala czytelnikom poznać strukturę dokumentacji oprogramowania, co ułatwi im szybki dostęp do potrzebnych informacji.

Aby pomóc w osiągnięciu tej spójności, możesz stworzyć przewodnik po stylach dokumentacji oprogramowania.

Twoje narzędzie do zarządzania dokumentacją oprogramowania może również zawierać funkcje, które pomogą Ci osiągnąć spójny styl.

Na przykład wtyczka Heroic Knowledge Base zawiera wstępnie stylizowane objaśnienia, które podkreślają kluczowe informacje lub ostrzeżenia. Korzystając z nich, możesz zapewnić spójne formatowanie całej dokumentacji.

Wykorzystaj ekspertów do napisania dokumentacji technicznej

W przypadku dokumentacji oprogramowania skierowanej do użytkownika może nie być potrzebny ekspert w danej dziedzinie do napisania treści.

Jednak w przypadku bardziej technicznej dokumentacji oprogramowania, takiej jak dokumentacja API przeznaczona dla programistów, prawdopodobnie będziesz chciał wyznaczyć osobę z odpowiednią wiedzą techniczną do napisania tych dokumentów.

Może to być oddany pisarz techniczny z doświadczeniem w dziedzinie, jeśli Twoja organizacja ma zasoby do zatrudnienia na to stanowisko. Lub może to być jeden z twoich programistów.

Ważne jest, aby autor rozumiał techniczne aspekty twojego oprogramowania na wystarczająco głębokim poziomie, aby wyjaśnić je innym użytkownikom technicznym.

Ułatw ludziom odkrywanie treści (wyszukiwanie/filtrowanie)

W miarę powiększania się biblioteki dokumentacji użytkownicy będą mieli coraz większe trudności ze znalezieniem artykułów w dokumentacji odpowiadających ich potrzebom.

Aby uniknąć tego problemu, należy skoncentrować się na poprawie wykrywalności dokumentacji oprogramowania.

Pierwszą strategią jest podzielenie dokumentacji według typu.

Na przykład zwykle chcesz oddzielić dokumentację użytkownika końcowego od dokumentacji oprogramowania dla programistów.

W ramach tego możesz także użyć kategorii do dalszego podziału artykułów. Możesz używać kategorii opartych na funkcjach, przypadkach użycia, dodatkach itd. — niezależnie od tego, co ma logiczny sens dla Twojego oprogramowania.

Zgodnie z tym samym przykładem Gravity Forms z powyższego, możesz zobaczyć, że Gravity Forms dzieli dokumentację użytkownika końcowego według typów funkcji.

Inną przydatną funkcją umożliwiającą wykrywanie są sugestie wyszukiwania na żywo. Użytkownicy mogą rozpocząć wpisywanie odpowiedniego zapytania w polu wyszukiwania i natychmiast zobaczyć artykuły z dokumentacją, które pasują do tego zapytania.

Wiele narzędzi dokumentacji zawiera wbudowaną funkcję wyszukiwania na żywo, w tym Heroic Knowledge Base.

Aktualizuj dokumentację swojego oprogramowania

Ponieważ Twoje oprogramowanie ciągle się zmienia, dokumentacja oprogramowania zawsze będzie w toku.

W miarę zmian w oprogramowaniu będziesz musiał niezwłocznie aktualizować dokumentację, aby odzwierciedlić te zmiany.

W przeciwnym razie twoja dokumentacja nie tylko nie będzie „nieprzydatna”, ale może w rzeczywistości powodować zamieszanie wśród użytkowników.

Aby mieć pewność, że te aktualizacje zostaną przeprowadzone, należy przypisać określone osoby do zarządzania dokumentacją i procesem aktualizacji. W ten sposób nie ma dwuznaczności co do tego, kto jest odpowiedzialny za zachowanie dokładności.

Skorzystaj z opinii klientów, aby ulepszyć swoją dokumentację

Oprócz posiadania własnego zespołu pracującego nad przeglądaniem i aktualizacją dokumentacji oprogramowania, warto również wziąć pod uwagę opinie klientów.

Klienci mogą przekazać cenne informacje o tym, jak pomocny (lub potencjalnie nieprzydatny) jest określony artykuł dokumentacji oprogramowania, a także szczegółowe informacje o tym, jak można go ulepszyć.

Aby zautomatyzować proces zbierania opinii od klientów, warto poszukać narzędzia do zarządzania dokumentacją, które zawiera wbudowane funkcje do zbierania opinii od klientów.

Na przykład wtyczka Heroic Knowledge Base pozwala użytkownikom ocenić artykuł jako pomocny lub nieprzydatny, a także opcjonalnie przekazać opinię w dowolnej formie.

Następnie możesz wyświetlić wszystkie te informacje z pulpitu nawigacyjnego, aby szybko znaleźć artykuły w dokumentacji, które należy poprawić.

Zacznij dokumentować swoje oprogramowanie już dziś

Dokumentacja oprogramowania pomaga Tobie i Twoim klientom pracować wydajniej i czerpać więcej korzyści z oprogramowania.

Istnieją różne typy dokumentacji oprogramowania, dlatego warto zastanowić się, które typy odpowiadają potrzebom Twojego projektu oprogramowania.

Możesz mieć inną dokumentację dla zespołów wewnętrznych lub zewnętrznych, a także dla różnych typów klientów, takich jak programiści i użytkownicy końcowi.

Aby stworzyć skuteczną dokumentację, będziesz chciał postępować zgodnie z najlepszymi praktykami z tego posta.

Aby opublikować tę dokumentację, możesz użyć narzędzia typu open source, takiego jak Heroic Knowledge Base, które jest oparte na potężnym oprogramowaniu WordPress.

Otrzymasz elastyczność i własność samoobsługowej platformy ze wszystkimi funkcjami i funkcjami potrzebnymi do publikowania wysokiej jakości dokumentacji oprogramowania.

Jeśli chcesz dowiedzieć się więcej, kliknij tutaj, aby przejść do heroicznej bazy wiedzy.