18 Software Documentation Tools that Do The Hard Work For You

🟢 Bonus material: Git Workflow Checklist to simplify & streamline version management

Bez dokumentacji, oprogramowanie jest tylko czarną skrzynką. A czarne skrzynki nie są nigdzie w pobliżu tak użyteczne, jak mogłyby być, ponieważ ich wewnętrzne działanie jest ukryte przed tymi, którzy potrzebują ich na jawie.

Dokumentacja oprogramowania zmienia Twoje oprogramowanie w szklane pudełko, wyjaśniając użytkownikom i programistom, jak ono działa lub jest używane.

Prawdopodobnie widziałeś już dokumentację wcześniej, ale jeśli potrzebujesz odświeżenia, oto przykład z API Slacka:

Jak widzisz, Slack wyjaśnia wszystko na temat swojego API w najdrobniejszych szczegółach. Wszelkie powiązane strony są połączone, istnieje pasek boczny z łatwo dostępnymi tematami i zrzutami ekranu tego, co użytkownik może oczekiwać, że zobaczy.

Aby wyjaśnić to bardziej szczegółowo, zajmiemy się następującymi tematami w tym poście Process Street:

• Czym jest dokumentacja oprogramowania?
• Opcje hostingu dokumentacji oprogramowania
• Narzędzia do pisania dokumentacji oprogramowania
• Słowa końcowe na temat dokumentacji oprogramowania

Zacznijmy.

Co to jest dokumentacja oprogramowania?

„Dokumentacja w inżynierii oprogramowania jest terminem parasolowym, który obejmuje wszystkie pisemne dokumenty i materiały dotyczące rozwoju i użytkowania produktu oprogramowania” – Prototype.io, Software Documentation Types and Best Practices

Wszystkie elementy oprogramowania powinny mieć jakąś formę dokumentacji, która szczegółowo wyjaśnia, czym jest produkt, jak działa i dlaczego działa w ten sposób.

„If it isn’t documented, it doesn’t exist” – Sitepoint, A Guide to Writing Your First Software Documentation

Jako programista, twoim głównym celem jest napisanie najlepszego kodu, jaki tylko możesz. Chcesz, aby Twój kod był najlepszy w swojej klasie, łatwy do czytania, łatwy w użyciu i chcesz, aby w jego wyniku działy się wspaniałe rzeczy. Prawda?

Ale bez udokumentowania tego, co zrobiłeś i dlaczego to zrobiłeś:

• Nikt inny nie może używać twojego kodu, tylko ty

Bez dokumentacji, nikt nie zrozumie, co zrobiłeś i dlaczego to zrobiłeś. Będzie to niewiarygodnie trudne, wręcz niemożliwe, dla kogoś innego, aby podnieść twój kod i pracować nad nim. Mogą nawet go zezłomować i zacząć od nowa, ponieważ w niektórych przypadkach będzie to szybsze niż próba rozpracowania tego, co zrobiłeś i dlaczego.

• Nie możesz go zaktualizować ani poprawić

Czy pamiętasz, co jadłeś na obiad w sobotę, trzy miesiące temu? O ile nie jesteś kompletnym stworzeniem z przyzwyczajenia, są szanse, że nie możesz. Można więc powiedzieć, że prawdopodobnie nie będziesz pamiętał kodu, który napisałeś dwa, trzy, cztery miesiące po tym, jak go zrobiłeś. Jeśli nie pamiętasz powodów stojących za twoimi decyzjami dotyczącymi kodowania, to będziesz walczył o możliwość jego aktualizacji lub ulepszenia.

Mimo tego, dokumentacja oprogramowania jest często zadaniem, które jest wykonywane w pośpiechu, źle, jest traktowane priorytetowo lub całkowicie zapomniane.

Zanim zaczniemy rozmawiać o tym, jakich narzędzi można użyć do pisania dokumentacji oprogramowania, musimy pomyśleć o tym, jak upewnić się, że zadanie to zostanie wykonane w pierwszej kolejności.

W tym właśnie może pomóc Process Street.

Process Street to oprogramowanie do zarządzania procesami biznesowymi (BPM), które może być używane do tworzenia, zarządzania i śledzenia procesów.

Więcej o tym, czym jest Process Street, dowiesz się później, ale na razie pozwól, że pokażę Ci, jak możesz go użyć jako narzędzia, które pomoże Ci dopasować dokumentację oprogramowania do każdego projektu rozwoju oprogramowania, nad którym pracujesz.

Poniżej znajduje się przykład gotowego szablonu Software Deployment Process. Ten szablon został stworzony, aby pomóc inżynierom oprogramowania i programistom wdrażać ich oprogramowanie w najlepszy możliwy sposób.

Kliknij tutaj, aby uzyskać dostęp do Software Deployment Process!

Aby otrzymać ten szablon, albo zaloguj się i dodaj go do swojego pulpitu nawigacyjnego, albo zapisz się na bezpłatną wersję próbną.

Ten szablon jest doskonałym przykładem procesu, który można wykonać za każdym razem, gdy chcesz wdrożyć nowy lub zaktualizowany fragment kodu.

Zawiera on jasne kroki, które przeprowadzą Cię przez cały proces wdrażania, od ustawienia środowiska staging do wprowadzenia zmian na żywo. Te kroki upewnią się, że nic nie zostanie pominięte i że cały proces przebiega gładko za każdym razem.

Zaprojektowaliśmy ten szablon, aby być używane jako przewodnik, aby pomóc Ci stworzyć proces wdrażania, który działa dla Ciebie. Każda firma jest inna, każdy projekt oprogramowania jest inny, a każdy proces wdrażania jest inny.

Możesz edytować ten proces i dodać w zadaniach, które są istotne dla Ciebie, Twojej firmy i Twojego projektu.

Co sprowadza mnie z powrotem do dokumentacji oprogramowania; możesz dodać „dokumentację oprogramowania” jako zadanie. W ten sposób każdy, kto pracuje w procesie wdrażania oprogramowania, zostanie przypomniany i zachęcony do ukończenia tego, jako część procesu.

Mam jeszcze kilka gotowych szablonów procesów, które mogą być dla ciebie przydatne, które załączę na końcu tego postu.

Zanim do tego dojdziemy, spójrzmy na to, gdzie możesz przechowywać swoją dokumentację oprogramowania.

Opcje hostingu dokumentacji oprogramowania

Nie jest dobrze mieć tylko garść plików tekstowych żyjących na twoim komputerze. Muszą być one dostępne dla programistów i użytkowników, co najprawdopodobniej zostanie osiągnięte przez hosting dokumentów w Internecie, ponieważ nie są to lata 80-te.

Process Street (do użytku wewnętrznego)

Dla szkolenia nowych programistów i utrzymywania dokumentacji w jednym miejscu, Process Street jest solidnym wyborem dla dokumentacji oprogramowania.

Po pierwsze, możesz stworzyć proces pisania dokumentacji, aby upewnić się, że uchwyciłeś wszystkie właściwe szczegóły i uczyniłeś ją tak użyteczną, jak to tylko możliwe.

Korzystając z następujących łatwych w użyciu funkcji, możesz następnie napisać i przechowywać swoją dokumentację w jednym miejscu:

• Widżety obrazów
• Widżety tekstu
• Widżety wideo
• Widżety plików
• Widżety podzadań
• Widżety e-mail
• Widżety osadzania

Przechowywanie dokumentacji w Process Street oznacza, że dostęp do niej ma każdy w firmie. Można ją udostępniać innym, wysyłać do zatwierdzenia, ustawiać przypomnienia o konieczności jej przeglądu i łatwo aktualizować.

Sprawdź to:

Jeśli można to udokumentować, można to udokumentować w Process Street.

Zapisz się na bezpłatną wersję próbną tutaj i daj sobie z tym spokój.

Read The Docs

To niezwykłe, że Read The Docs jest darmowe, kiedy widzisz wszystko, co może zrobić. Podobnie jak w przypadku GitHub, możesz stworzyć tyle materiałów open-source, ile chcesz, które zostaną otwarcie zindeksowane na stronie, ale będzie cię to kosztować, jeśli chcesz, aby dokumenty były prywatne i wewnętrzne dla twojej firmy. Dla naszych celów jest prawdopodobne, że będziesz zadowolony z tego, że dokumenty są łatwo dostępne dla użytkowników w sieci.

Powodem, dla którego Read The Docs jest tak dobre, jest możliwość bezproblemowego importowania dokumentacji z dowolnego systemu kontroli wersji, w tym Git, Mercurial, Subversion i Bazaar. Obsługuje również webhooki, więc dokumenty są budowane automatycznie za każdym razem, gdy popełniasz kod.

Sprawdź ich przewodnik Getting Started, aby dowiedzieć się, jak to działa i jak zachowują się twoje dokumenty, gdy są tam hostowane.

GitHub (& GitHub Pages)

Jeśli używasz GitHuba do zarządzania kontrolą wersji swojego oprogramowania, masz, co najmniej, plik README.MD w repozytorium. Aby używać GitHuba do dokumentowania swojego oprogramowania, tak jak miliony innych osób robiły to w przeszłości, wystarczy wypełnić README markdownem.

Świetnym przykładem jest repozytorium t sferika, zrzut ekranu tutaj:

Jeśli chcesz czegoś więcej niż tylko jednego arkusza sformatowanego tekstu, możesz skorzystać z narzędzia Pages na GitHubie (dostajesz jedną darmową stronę internetową + hosting z każdym kontem GitHuba, a nawet możesz przekierować do niej niestandardową domenę). Pages ma nawet świetnie wyglądające domyślne motywy, które sprawiają, że twoja dokumentacja wygląda profesjonalnie.

Powyżej znajduje się dokumentacja atom.io dla Electron hostowana na GitHubie. Jest to mądry wybór, ponieważ automatycznie współpracuje z kontrolą wersji GitHuba, tak jak reszta Twojego oprogramowania. Zobacz repozytorium witryny tutaj.

Dropbox Paper (do użytku wewnętrznego)

Dla wewnętrznego użytku dokumentacji oprogramowania Dropbox Paper jest doskonałym wyborem. Podobnie jak jego poprzednik Hackpad, możesz go użyć do stworzenia prywatnej wiki dla pracowników. Możesz łączyć ze sobą dokumenty, wstawiać bloki kodu, obrazy i skoki stron, tak jak wymagałbyś tego od każdego narzędzia do tworzenia dokumentacji.

Jak widać w komentarzach po prawej stronie, możesz go również używać do przechodzenia przez procesy zatwierdzania i współpracy nad tworzeniem dokumentacji. Ogólnie rzecz biorąc, jest to świetne narzędzie do wewnętrznego rozwoju i tworzenia dokumentacji, być może z zamiarem upublicznienia jej później lub po prostu zachowania jej do użytku wewnętrznego.

Atlassian REST API Browser (do użytku API)

Atlassian’s REST API Browser (RAB) jest domyślnie włączony do JIRA Server, Confluence Server i Stash. Jest zbudowana do odkrywania API dostępnych do użytku w środowiskach JIRA/Confluence, a także jako miejsce do przechowywania dokumentacji. Jeśli, oczywiście, Twój interfejs API pasuje do tej listy.

Dokumentuj swój interfejs API za pomocą tego narzędzia, aby Twój interfejs API zgodny z JIRA/Confluence był bardziej widoczny. Sprawdź tutaj dokumentację firmy Atlassian na ten temat.

Tettra (do użytku wewnętrznego)

Tettra to rodzaj bazy wiedzy, w której można udokumentować swój rozwój lub cokolwiek innego.

Tettry używamy wewnętrznie w Process Street do wielu zastosowań. Na co dzień używam Tettry, aby mieć jedno miejsce, w którym wszystkie moje procesy są udokumentowane, dzięki czemu nigdy nie zapomnę, jak jeden wiąże się z drugim lub jak zostały skonfigurowane różne zbudowane przez nas automaty.

Tettra jest świetna, jeśli chcesz stworzyć swego rodzaju bibliotekę. Oznacza to, że świetnie nadaje się do tworzenia dokumentacji oprogramowania, a nawet jako wewnętrzne wiki dla Twojej firmy.

Zważywszy, że Tettra została zaprojektowana specjalnie do zarządzania wiedzą, posiada również wiele innych funkcji pomocniczych. Na przykład może zasugerować, jakie dodatkowe treści lub sekcje można dodać, aby uzyskać pełniejszy obraz organizacji i tego, jak wszystko do siebie pasuje.

Możesz zobaczyć tutaj mały filmik o tym, jak zespół programistów może używać Tettry: How Product & Engineering Teams Use Tettra.

Or, you can go here to read about how we use Tettra alongside Process Street: Automatyzacja przepływów pracy i list kontrolnych: Process Street Case Study.

Check it out!

Apiary (do użytku API)

As well as being a place where bees live, Apiary is a dedicated host for API documentation. Pisz w markdownie, dodawaj wyśmiewane wywołania API, a Apiary zestawi to w coś takiego, jak widzisz poniżej:

Każdy może przetestować API bez konieczności wchodzenia do aplikacji lub faktycznego programowania wywołania, co czyni go super dostępnym sposobem na udostępnienie API, dogłębne udokumentowanie go i pochwalenie się tym, co potrafi.

Przedyskutowaliśmy już gdzie przechowywać dokumentację oprogramowania, teraz czas przyjrzeć się jak ją napisać.

Narzędzia do pisania dokumentacji oprogramowania

Dokumentacja oprogramowania jest często pisana w markdown, aby umożliwić tworzenie hiperłączy i formatowanie, a jednocześnie zachować ją jako zwykły tekst, aby mogła żyć obok plików z kodem w kontroli wersji. Oznacza to, że wiele z moich wyborów narzędzi do pisania to proste edytory markdown, które sprawiają, że pisanie staje się przyjemne. Dodatkowo, jest też kilka bardzo skutecznych rozwiązań, które nie są markdownowe.

MarkdownPad (Windows)

Mając wersję darmową i premium – obie z mnóstwem świetnych funkcji – MarkdownPad jest najpopularniejszym edytorem markdown dla Windows. Jest zoptymalizowany pod kątem wpisów na blogach, stron internetowych, artykułów, README i, oczywiście, dokumentacji oprogramowania.

Możesz pobrać MarkdownPad za darmo lub uzyskać wersję premium za $14.95.

iA Writer (Mac)

iA Writer to prosty, piękny edytor markdown z funkcją biblioteki, co oznacza, że możesz łatwo odwoływać się do innych dokumentów na pasku bocznym. Brakuje w nim wewnętrznych odnośników między dokumentami, których można by się spodziewać w dokumentach programowych, ale zawsze można je usunąć, gdy dokument jest już w ostatecznej formie (czyli gdy ma trafić do internetu w postaci strony).

Jeśli napiszesz całą dokumentację w postaci jednej, rozbitej strony, możesz użyć kotwic przeskoku strony, aby pomóc użytkownikom w nawigacji.

iA Writer kosztuje $9,99 w Mac App Store.

ProProfs Knowledge Base

Profs Knowledge Base to fantastyczne małe narzędzie do wszystkich etapów tworzenia dokumentów; od pisania i edycji, po dostosowywanie, ustawianie przepływów pracy i publikowanie. Możesz dodawać multimedia, importować istniejącą zawartość z word docs, PDF lub PPT, zapisywać wiele wersji dokumentu i przywracać je w razie potrzeby.

Ale prawdziwe piękno tego narzędzia leży w jego użyteczności. Każdy może go używać do tworzenia dokumentacji oprogramowania. Niezależnie od tego, czy dokumentujesz oprogramowanie od lat, czy też dopiero niedawno zacząłeś, jest to niewiarygodnie proste i łatwe w użyciu narzędzie.

Profs jest darmowy w użyciu, lub możesz go uaktualnić do pakietu premium, który kosztuje 112 dolarów miesięcznie.

SimpleMDE (przeglądarka)

Choć technicznie rzecz biorąc, możesz pisać markdown w dowolnym edytorze tekstu, ponieważ jest to sposób na formatowanie zwykłego tekstu, a nie ściśle „narzędzie”, nie zaskoczy cię, że jest to również możliwe w twojej przeglądarce! SimpleMDE to zarówno funkcjonalny edytor markdown oparty na JavaScripcie, jak i projekt open-source, z którego można się uczyć i adaptować na własny użytek, jeśli zajdzie taka potrzeba.

SimpleMDE jest w 100% darmowy! Pobierz źródło na GitHubie tutaj.

EdytoryreStructuredText

Markdown jest jednym z dwóch najczęściej używanych języków do pisania dokumentacji oprogramowania, ale jest jeszcze jeden, któremu do tej pory się nie przyjrzeliśmy, a jest nim reStructuredText. Jest on bardzo podobny do markdown, ale warto się go nauczyć dla celów dokumentacji oprogramowania.

Docutils, twórca reStructuredText, zebrał tutaj listę edytorów reStructuredText, która obejmuje:

Punktem reStructuredText jest to, że łatwo jest konwertować między różnymi formatami, zwłaszcza z czystego tekstu na statyczną stronę internetową. Zobacz więcej informacji tutaj.

Narzędzia do automatycznego generowania dokumentacji z kodu źródłowego

Nie ma to jak ludzki dotyk, jeśli chodzi o dokumentację (widać to wyraźnie w dokumentach Slacka i Giphy, by wymienić tylko kilka). Jednakże, jako punkt wyjścia (szczególnie dla ogromnych bibliotek źródłowych), najlepiej jest generować dokumentację szkieletową automatycznie. Ta praca polega na analizie funkcji i komentarzy źródła, a istnieje kilka różnych opcji w zależności od języka:

Przed pójściem naprzód i poleganiem wyłącznie na automatycznym generowaniu, sugerowałbym przeczytanie tego wątku StackExchange, który waży plusy i minusy.

Słowa końcowe na temat dokumentacji oprogramowania

Jest mnóstwo wymyślnych rozwiązań, szybkich poprawek i narzędzi, które (szczerze mówiąc) są prawie identyczne. W ostatecznym rozrachunku liczy się to, że

Najważniejsze, w ostatecznym rozrachunku, jest to, że:

a) piszesz dokumentację oprogramowania dla każdego kawałka oprogramowania, które budujesz
b) piszesz ją kompleksowo i hostujesz ją gdzieś, gdzie użytkownik może mieć do niej dostęp

Wspomniałem wcześniej, że mam jeszcze kilka szablonów procesów rozwojowych, które mógłbyś chętnie sprawdzić?

Cóż, oto one…

Szablony procesów rozwojowych Process Street

Zanim udostępnię Ci te szablony, pozwól, że wyjaśnię, czym jest Process Street.

Wiemy więc, że Process Street to listy kontrolne o dużej mocy. Jest to oprogramowanie, które pomoże Ci tworzyć procesy i zarządzać nimi.

Ale zaraz, Process Street to coś więcej!

Zobacz film wprowadzający, aby dowiedzieć się, co mam na myśli:

Więc widzisz, że nie tylko możesz stworzyć szablon procesu rozwoju i uruchamiać z niego poszczególne listy kontrolne za każdym razem, gdy musisz zakończyć proces rozwoju, ale możesz go dostosować za pomocą tych dodatkowych funkcji

• Zatrzymywanie zadań
• Dynamiczne daty wymagalności
• Uprawnienia do zadań
• Logika warunkowa
• Zadania zatwierdzania
• Widżet osadzania
• Przypisywanie ról

Przypisuj zadania, uzyskać zatwierdzenie, wymusić kolejność, w jakiej zadania są wykonywane, i możesz połączyć ten proces z tysiącami aplikacji za pomocą Zapier, webhooków lub integracji API.

Obejrzyj webinarium na temat naszych najnowszych funkcji i zobacz, jak możesz je w pełni wykorzystać:

Mając to wszystko na uwadze, spójrz na poniższe gotowe szablony:

Kontrola bezpieczeństwa sieci

Ten szablon może być używany przez menedżera ryzyka lub równoważnego specjalistę IT do oceny sieci pod kątem luk w zabezpieczeniach.

Kliknij tutaj, aby uzyskać dostęp do listy kontrolnej audytu bezpieczeństwa sieci!

Miesięczna lista kontrolna konserwacji witryny internetowej

Użyj tej miesięcznej listy kontrolnej do optymalizacji szybkości ładowania witryny, skanowania pod kątem luk w zabezpieczeniach i sprawdzania widoczności w wyszukiwarkach.

Kliknij tutaj, aby uzyskać dostęp do miesięcznej listy kontrolnej konserwacji witryny internetowej!

Tutorial testowania oprogramowania

Ten proces może być używany do zarządzania całym projektem rozwoju oprogramowania od początku do końca, w tym projektowania, obsługi klienta, a także kontroli po uruchomieniu.

Kliknij tutaj, aby uzyskać dostęp do Software Testing Tutorial!

I oto masz to.

Jesteś teraz wolny, aby użyć czegokolwiek, co czyni twoje życie łatwiejszym. Mam nadzieję, że znajdziesz swoje nowe ulubione narzędzie na tej liście.