18 Software Documentation Tools that Do The Hard Work For You

🟢 Bonusový materiál: Kontrolní seznam pracovních postupů systému Git pro zjednodušení & zefektivnění správy verzí

Bez dokumentace je software jen černá skříňka. A černé skříňky nejsou zdaleka tak užitečné, jak by mohly být, protože jejich vnitřní fungování je skryté před těmi, kteří je potřebují naostro.

Dokumentace softwaru promění váš software ve skleněnou skříňku tím, že uživatelům a vývojářům vysvětlí, jak funguje nebo se používá.

S dokumentací jste se již pravděpodobně setkali, ale pokud si ji potřebujete osvěžit, zde je příklad z rozhraní API společnosti Slack:

Jak vidíte, společnost Slack vysvětluje vše o svém rozhraní API do nesnesitelných podrobností. Veškeré související stránky jsou propojeny, je zde postranní panel se snadno přístupnými tématy a snímky obrazovky, které může uživatel očekávat.

Abychom to vysvětlili podrobněji, budeme se v tomto příspěvku na Process Street zabývat následujícími tématy:

• Co je to softwarová dokumentace?
• Možnosti hostingu softwarové dokumentace
• Nástroje pro psaní softwarové dokumentace
• Slova na závěr o softwarové dokumentaci

Začněme.

Co je to softwarová dokumentace

„Dokumentace v softwarovém inženýrství je zastřešující pojem, který zahrnuje všechny písemné dokumenty a materiály zabývající se vývojem a používáním softwarového produktu.“ – Prototype.io, Software Documentation Types and Best Practices

Všechny kusy softwaru by měly mít nějakou formu dokumentace, která podrobně vysvětluje, co je produkt zač, jak funguje a proč tak funguje.

„Pokud to není zdokumentováno, tak to neexistuje.“ – Sitepoint, Průvodce psaním první softwarové dokumentace

Jako vývojáři se snažíte především napsat co nejlepší kód. Chcete, aby váš kód byl nejlepší ve své třídě, snadno čitelný, snadno použitelný a aby se díky němu děly skvělé věci. Je to tak?

Ale bez zdokumentování toho, co jste udělali a proč jste to udělali:

• Nikdo jiný než vy nemůže váš kód používat

Bez dokumentace nikdo nepochopí, co jste udělali a proč jste to udělali. Pro někoho jiného bude neuvěřitelně obtížné, téměř nemožné, vzít váš kód a pracovat na něm. Možná ho dokonce zahodí a začne znovu, protože v některých případech to bude rychlejší než se snažit přijít na to, co jste udělali a proč.

• Nemůžete ho aktualizovat ani vylepšit

Pamatujete si, co jste před třemi měsíci v sobotu jedli k večeři? Pokud nejste úplný tvor zvyku, je pravděpodobné, že ne. Takže se dá říct, že si pravděpodobně nebudete pamatovat kód, který jste napsali, dva, tři, čtyři měsíce poté, co jste ho vytvořili. Pokud si nepamatujete důvody, které stály za vašimi rozhodnutími při kódování, pak budete mít problém s tím, abyste jej mohli aktualizovat nebo vylepšit.

Přesto je dokumentace softwaru často úkolem, který se uspěchá, udělá se špatně, upřednostní se nebo se na něj úplně zapomene.

Než se začneme bavit o tom, jaké nástroje lze k psaní softwarové dokumentace použít, musíme se zamyslet nad tím, jak zajistit, aby byl tento úkol vůbec splněn.

Tady nám může pomoci společnost Process Street.

Process Street je software pro řízení podnikových procesů (BPM), který lze použít k vytváření, správě a sledování procesů.

O tom, co je Process Street, se dozvíte později, prozatím vám ukážu, jak jej můžete použít jako nástroj, který vám pomůže začlenit softwarovou dokumentaci do každého projektu vývoje softwaru, na kterém pracujete.

Níže je příklad předpřipravené šablony procesu nasazení softwaru. Tato šablona byla vytvořena s cílem pomoci softwarovým inženýrům a programátorům co nejlépe nasadit jejich software.

Klikněte zde pro přístup k Procesu nasazení softwaru!

Chcete-li získat tuto šablonu, buď se přihlaste a přidejte si ji na ovládací panel, nebo se přihlaste k bezplatné zkušební verzi.

Tato šablona je dokonalým příkladem procesu, kterým se můžete řídit pokaždé, když chcete nasadit nový nebo aktualizovaný kus kódu.

Má jasné kroky, které vás provedou celým procesem nasazení, od nastavení prostředí staging až po uvedení změn do ostrého provozu. Tyto kroky zajistí, že nic nevynecháte a že celý proces proběhne pokaždé hladce.

Tuto šablonu jsme navrhli tak, aby sloužila jako průvodce, který vám pomůže vytvořit proces nasazení, který vám bude vyhovovat. Každá společnost je jiná, každý softwarový projekt je jiný a každý proces nasazení je jiný.

Tento proces můžete upravovat a přidávat do něj úkoly, které se týkají vás, vaší společnosti a vašeho projektu.

Což mě přivádí zpět k softwarové dokumentaci; můžete přidat „softwarovou dokumentaci“ jako úkol. Tímto způsobem bude každému, kdo pracuje na procesu zavádění softwaru, připomenuto a doporučeno, aby jej v rámci tohoto procesu dokončil.

Mám několik dalších předpřipravených šablon procesů, které by se vám mohly hodit, a které uvedu na konci tohoto příspěvku.

Než se k tomu dostaneme, podívejme se na to, kam můžete svou softwarovou dokumentaci uložit.

Možnosti hostování softwarové dokumentace

Není dobré mít v počítači jen hromadu textových souborů. Musí být přístupné vývojářům a uživatelům, což s největší pravděpodobností zajistíte hostováním dokumentace na internetu, protože to nejsou 80. léta.

Process Street (pro interní použití)

Pro školení nových vývojářů a udržování dokumentace na jednom místě je Process Street solidní volbou pro softwarovou dokumentaci.

Nejprve byste si mohli vytvořit proces psaní dokumentace, abyste měli jistotu, že zachytíte všechny správné detaily a že bude co nejužitečnější.

Pomocí následujících snadno použitelných funkcí pak můžete svou dokumentaci sepsat a uložit na jediném místě:

• Obrázkové widgety
• Textové widgety
• Video widgety
• Souborové widgety
• Dílčí úkoly
• Emailové widgety
• Embed widgety

Uložení vaší dokumentace v rámci Process Street znamená, že k ní mají přístup všichni ve firmě. Můžete ji sdílet s ostatními, posílat ji ke schválení, nastavovat upomínky k jejímu přezkoumání a snadno ji aktualizovat.

Vyzkoušejte si to:

Jestliže to lze zdokumentovat, lze to zdokumentovat v Process Street.

Přihlaste se k bezplatné zkušební verzi zde a vyzkoušejte to.

Read The Docs

Je pozoruhodné, že Read The Docs je zdarma, když vidíte, co všechno umí. Podobně jako na GitHubu můžete vytvářet libovolné množství materiálů s otevřeným zdrojovým kódem, které se na webu otevřeně indexují, ale pokud chcete, aby dokumenty byly soukromé a interní pro vaši společnost, bude vás to něco stát. Pro naše účely vám pravděpodobně nebude vadit, když budou dokumenty snadno dostupné uživatelům na webu.

Důvod, proč je Read The Docs tak dobrý, je ten, že můžete bez námahy importovat dokumentaci z jakéhokoli systému pro správu verzí, včetně systémů Git, Mercurial, Subversion a Bazaar. Podporuje také webové háčky, takže se dokumentace automaticky vytvoří vždy, když odevzdáte kód.

Podívejte se na jejich průvodce pro začátečníky, abyste získali představu o tom, jak to funguje a jak by se vaše dokumentace chovaly, kdybyste je tam hostovali.

GitHub (& Stránky GitHub)

Pokud používáte GitHub pro správu verzí svého softwaru, máte v úložišti minimálně soubor README.MD. Chcete-li používat GitHub pro dokumentaci svého softwaru, jako to v minulosti udělaly miliony jiných, stačí tento soubor README vyplnit pomocí markdown.

Skvělým příkladem je repozitář t společnosti sferik, jehož screenshot najdete zde:

Pokud chcete více než jen jeden list formátovaného textu, můžete využít nástroj Pages služby GitHub (ke každému účtu GitHub dostanete jednu webovou stránku zdarma + hosting a můžete na ni dokonce nasměrovat vlastní doménu). Pages má dokonce skvěle vypadající výchozí motivy, díky kterým bude vaše dokumentace vypadat profesionálně.

Nahoře je dokumentace atom.io pro Electron hostovaná na GitHubu. Je to chytrá volba, protože automaticky spolupracuje se správou verzí GitHubu, stejně jako zbytek vašeho softwaru. Úložiště webu najdete zde.

Dropbox Paper (pro interní použití)

Pro interní použití softwarové dokumentace je Dropbox Paper vynikající volbou. Stejně jako jeho předchůdce Hackpad jej můžete použít k vytvoření soukromé wiki pro zaměstnance. Můžete propojovat dokumenty, vkládat bloky kódu, obrázky a přeskakovat stránky, stejně jako to požadujete od jakéhokoli dokumentačního nástroje.

Jak vidíte z komentářů vpravo, můžete jej také použít ke schvalovacím procesům a spolupráci nad tvorbou dokumentace. Celkově je to skvělý nástroj pro interní vývoj a tvorbu dokumentace, třeba s výhledem na její pozdější zveřejnění, nebo jen pro interní použití.

Prohlížeč API REST společnosti Atlassian (pro použití API)

Prohlížeč API REST společnosti Atlassian (RAB) je standardně součástí instancí JIRA Server, Confluence Server a Stash. Je vytvořen pro zjišťování API dostupných pro použití v prostředích JIRA/Confluence a také jako místo pro umístění vaší dokumentace. Pokud ovšem vaše API vyhovuje.

Dokumentujte své API pomocí tohoto nástroje, abyste své API kompatibilní s JIRA/Confluence více zviditelnili. Podívejte se zde na dokumentaci společnosti Atlassian, jak na to.

Tettra (pro interní použití)

Tettra je jakýsi software znalostní báze, kde můžete dokumentovat svůj vývoj nebo vůbec cokoli.

Tettra používáme interně ve společnosti Process Street pro řadu případů použití. Denně používám Tettra k tomu, abych měl na jednom místě zdokumentované všechny své procesy, abych nikdy nezapomněl, jak jeden souvisí s druhým nebo jak byly nastaveny různé automatizace, které jsme vytvořili.

Tettra je skvělá, pokud chcete vytvořit jakousi knihovnu. To znamená, že se skvěle hodí pro softwarovou dokumentaci nebo třeba jen jako interní wiki vaší společnosti.

Vzhledem k tomu, že je Tettra speciálně navržena pro správu znalostí, je vybavena i řadou dalších podpůrných funkcí. Například dokáže navrhnout, jaký další obsah nebo sekce byste mohli chtít přidat, abyste získali ucelenější obraz o vaší organizaci a o tom, jak do sebe věci zapadají.

Zde se můžete podívat na malé video, jak by mohl vypadat tým vývojářů, kteří chtějí Tettra používat:

Nebo si zde můžete přečíst, jak používáme Tettra spolu s Process Street: Automatizace pracovních postupů a kontrolních seznamů:

Apiary (pro použití API)

Kromě toho, že je Apiary místem, kde žijí včely, je také specializovaným hostitelem pro dokumentaci API. Pište v markdown, přidejte makety volání API a Apiary to srovná do něčeho, co vidíte níže:

Každý může testovat API, aniž by musel jít do aplikace nebo skutečně programovat volání, což z něj dělá super přístupný způsob, jak sdílet své API, důkladně ho dokumentovat a chlubit se tím, co umí.

Probrali jsme, kam dokumentaci k softwaru ukládat, nyní je čas podívat se na to, jak ji psát.

Nástroje pro psaní softwarové dokumentace

Softwarová dokumentace se často píše v jazyce markdown, aby umožňovala hypertextové odkazy a formátování a zároveň zůstala prostým textem, takže může žít vedle souborů kódu ve správě verzí. To znamená, že mnoho mých voleb nástrojů pro psaní dokumentace jsou jednoduché editory markdown, které zpříjemňují psaní. Kromě toho je tam vhozeno i několik velmi účinných řešení bez markdown.

MarkdownPad (Windows)

S bezplatnou a prémiovou verzí – obě se spoustou skvělých funkcí – je MarkdownPad nejoblíbenějším editorem markdown pro Windows. Je optimalizován pro příspěvky na blogy, webové stránky, články, README a samozřejmě softwarovou dokumentaci.

MarkdownPad můžete získat zdarma nebo si pořídit prémiovou verzi za 14,95 USD.

iA Writer (Mac)

iA Writer je jednoduchý, krásný editor markdown s funkcí knihovny, což znamená, že můžete snadno odkazovat zpět na jiné dokumenty v postranním panelu. Chybí v něm sice vnitřní odkazy mezi dokumenty, jaké byste v softwarových dokumentech očekávali, ale ty si vždy můžete nechat projít, až bude dokument ve finální podobě (tedy pokud skončí na internetu na nějakém webu).

Píšete-li celou dokumentaci na jedné rozdělené stránce, můžete uživatelům usnadnit orientaci pomocí kotev pro skok na stránku.

iA Writer stojí 9,99 USD v Mac App Store.

ProProfs Knowledge Base

ProProfs Knowledge Base je fantastický malý nástroj pro všechny fáze tvorby dokumentů; od psaní a úprav, přes přizpůsobení, nastavení pracovních postupů až po publikování. Můžete přidávat multimédia, importovat existující obsah z dokumentů Word, PDF nebo PPT, ukládat více verzí dokumentu a v případě potřeby je obnovovat.

Skutečná krása tohoto nástroje však spočívá v jeho použitelnosti. K vytvoření softwarové dokumentace jej může použít kdokoli a kdokoli. Ať už dokumentujete software léta, nebo jste s tím začali teprve nedávno, je to neuvěřitelně jednoduchý a snadno použitelný nástroj.

ProProfs je k dispozici zdarma, nebo můžete přejít na prémiový balíček, který stojí 112 dolarů měsíčně.

SimpleMDE (prohlížeč)

Ačkoli technicky můžete psát markdown v jakémkoli textovém editoru, protože se jedná o způsob formátování prostého textu, nikoli striktně o „nástroj“, nepřekvapí vás, že je to možné i v prohlížeči! SimpleMDE je jednak funkční editor markdown postavený na JavaScriptu, jednak projekt s otevřeným zdrojovým kódem, ze kterého se můžete učit a v případě potřeby si jej přizpůsobit pro vlastní použití.

SimpleMDE je 100% zdarma! Zdrojový kód získáte na GitHubu zde.

reStructuredText editory

Markdown je jedním ze dvou nejpoužívanějších jazyků pro psaní softwarové dokumentace, ale existuje ještě jeden, kterému jsme se zatím nevěnovali, a tím je reStructuredText. Je velmi podobný markdownu, ale pro účely softwarové dokumentace stojí za to se jej naučit.

Docutils, tvůrce reStructuredText, zde sestavil seznam editorů reStructuredText, který obsahuje např:

Smyslem reStructuredText je snadná konverze mezi různými formáty, zejména z prostého textu na statickou webovou stránku. Více informací najdete zde.

Nástroje pro automatické generování dokumentace ze zdrojového kódu

Nic se nevyrovná lidskému přístupu, pokud jde o dokumentaci (je to vidět například v dokumentech Slack a Giphy). Nicméně jako výchozí bod (zejména u obrovských zdrojových knihoven) je nejlepší generovat kostru dokumentace automaticky. To funguje na základě analýzy funkcí a komentářů zdrojového kódu a existuje několik různých možností v závislosti na jazyce:

Než se začnete spoléhat pouze na automatické generování, doporučuji přečíst si toto vlákno StackExchange, které zvažuje výhody a nevýhody.

Slova na závěr o softwarové dokumentaci

Existuje spousta efektních řešení, rychlých oprav a nástrojů, které jsou (upřímně řečeno) téměř totožné. Na čem nakonec záleží, je to, že

Na čem nakonec záleží nejvíce, je to, že:

a) napíšete softwarovou dokumentaci pro každý kus softwaru, který vytváříte
b) napíšete ji komplexně a umístíte ji na místo, ke kterému má uživatel přístup

Již dříve jsem se zmínil, že mám několik dalších šablon vývojových procesů, které byste možná rádi vyzkoušeli?

No, tady jsou…

Šablony vývojových procesů Process Street

Než vám tyto šablony dám, dovolte mi, abych vám trochu více vysvětlil, co je Process Street.

Takže víme, že Process Street jsou supervýkonné kontrolní seznamy. Je to software, který vám pomůže vytvářet a spravovat procesy.

Ale počkejte, Process Street toho nabízí víc!

Podívejte se na toto úvodní video a zjistěte, co mám na mysli:

Takže vidíte, že můžete nejen vytvořit šablonu vývojového procesu a z ní spouštět jednotlivé kontrolní seznamy pokaždé, když potřebujete dokončit vývojový proces, ale můžete si ji přizpůsobit pomocí těchto dalších funkcí

• Zastavení úkolů
• Dynamické termíny
• Oprávnění k úkolům
• Podmíněná logika
• Schválení úkolů
• Embed widget
• Přiřazení rolí

Přiřazení úkolů, získat schválení, vynutit pořadí, v jakém se úkoly plní, a můžete tento proces propojit s tisíci aplikacemi prostřednictvím Zapier, webhooků nebo integrace API.

Podívejte se na webinář o našich nejnovějších funkcích a zjistěte, jak je můžete využít naplno:

Vzhledem k tomu všemu se podívejte na níže uvedené předpřipravené šablony:

Kontrolní seznam auditu zabezpečení sítě

Tuto šablonu může použít manažer rizik nebo obdobný IT odborník k posouzení sítě z hlediska bezpečnostních zranitelností.

Klikněte sem pro přístup ke kontrolnímu seznamu auditu zabezpečení sítě!

Měsíční kontrolní seznam údržby webových stránek

Tento měsíční kontrolní seznam údržby webových stránek můžete použít k optimalizaci rychlosti načítání webu, kontrole zranitelností a kontrole viditelnosti ve vyhledávání.

Kliknutím sem získáte přístup k měsíčnímu kontrolnímu seznamu údržby webových stránek!

Ukázka testování softwaru

Tento postup lze použít k řízení celého projektu vývoje softwaru od začátku do konce, včetně návrhu, práce s klienty a také kontroly po spuštění.

Kliknutím sem získáte přístup k výukovému kurzu testování softwaru!

A tady to máte.

Nyní můžete používat cokoli, co vám usnadní život. Doufám, že v tomto seznamu najdete svůj nový oblíbený nástroj.