18 szoftverdokumentációs eszköz, amely helyetted is elvégzi a nehéz munkát

🟢 Bónusz anyag: Git munkafolyamat ellenőrzőlista a verziókezelés egyszerűsítéséhez & racionalizálásához

Dokumentáció nélkül a szoftver csak egy fekete doboz. A fekete dobozok pedig közel sem olyan hasznosak, mint amilyenek lehetnének, mert a belső működésük el van rejtve azok elől, akiknek nyíltan szükségük van rájuk.

A szoftverdokumentáció üvegdobozzá változtatja a szoftverét, mivel elmagyarázza a felhasználóknak és a fejlesztőknek, hogyan működik vagy hogyan használják.

Valószínűleg láttál már dokumentációt, de ha szükséged van egy kis felfrissítésre, íme egy példa a Slack API-jából:

Amint láthatod, a Slack mindent kínzó részletességgel elmagyaráz az API-járól. Minden kapcsolódó oldal be van linkelve, van egy oldalsáv a könnyen elérhető témákkal, és képernyőképek mutatják, hogy mire számíthat a felhasználó.

Azért, hogy ezt részletesebben elmagyarázzuk, a következő témákkal foglalkozunk ebben a Process Street bejegyzésben:

• Mi a szoftverdokumentáció?
• Szoftverdokumentáció hosting lehetőségei
• Szoftverdokumentáció-íróeszközök
• Végszavak a szoftverdokumentációról

Lássunk hozzá.

Mi a szoftverdokumentáció?

“A dokumentáció a szoftverfejlesztésben olyan gyűjtőfogalom, amely magában foglal minden olyan írásos dokumentumot és anyagot, amely egy szoftvertermék fejlesztésével és használatával foglalkozik.” – Prototype.io, Software Documentation Types and Best Practices

Minden szoftverhez kell valamilyen dokumentáció, amely részletesen elmagyarázza, mi a termék, hogyan működik, és miért működik így.

“Ha nincs dokumentálva, akkor nem is létezik” – Sitepoint, A Guide to Writing Your First Software Documentation

A fejlesztőként az a fő célod, hogy a lehető legjobb kódot írd meg. Azt akarod, hogy a kódod a legjobb legyen, könnyen olvasható, könnyen használható, és azt akarod, hogy nagyszerű dolgok történjenek általa. Ugye?

De anélkül, hogy dokumentálnád, mit és miért csináltál:

• Senki más nem használhatja a kódodat, csak te

Dokumentáció nélkül senki nem fogja megérteni, mit és miért csináltál. Hihetetlenül nehéz lesz, szinte lehetetlen, hogy valaki más átvegye a kódodat és dolgozzon rajta. Még az is lehet, hogy elveti és újrakezdi, mivel bizonyos esetekben ez gyorsabb, mintha megpróbálná kitalálni, hogy mit és miért csináltál.

• Nem tudod frissíteni vagy javítani

Emlékszel arra, hogy mit ettél vacsorára szombaton, három hónappal ezelőtt? Hacsak nem vagy teljesen a megszokás rabja, nagy valószínűséggel nem tudod. Tehát joggal mondhatjuk, hogy valószínűleg nem fogsz emlékezni a kódra, amit írtál, két, három, négy hónappal azután, hogy megcsináltad. Ha nem emlékszik a kódolási döntései mögött meghúzódó okokra, akkor nehezen fogja tudni frissíteni vagy javítani.

Ennek ellenére a szoftver dokumentálása gyakran olyan feladat, amelyet elsietnek, rosszul végeznek el, háttérbe szorítanak, vagy teljesen megfeledkeznek róla.

Mielőtt elkezdenénk arról beszélni, hogy milyen eszközöket használhatunk a szoftverdokumentáció megírásához, ki kell találnunk, hogyan lehet biztosítani, hogy a feladatot egyáltalán elvégezzük.

Ez az, amiben a Process Street segíthet.

A Process Street egy olyan üzleti folyamatmenedzsment (BPM) szoftver, amely folyamatok létrehozására, kezelésére és követésére használható.

Még többet arról, hogy mi is a Process Street később, most hadd mutassam meg, hogyan használhatja eszközként, hogy segítsen beilleszteni a szoftverdokumentációt minden szoftverfejlesztési projektbe, amelyen dolgozik.

Az alábbiakban egy példa egy előre elkészített Szoftvertelepítési folyamat sablonra. Ez a sablon azért készült, hogy segítsen a szoftvermérnököknek és programozóknak a lehető legjobb módon telepíteni a szoftverüket.

Kattintson ide a Szoftvertelepítési folyamat eléréséhez!

A sablon megszerzéséhez vagy jelentkezzen be, és adja hozzá a műszerfalához, vagy iratkozzon fel az ingyenes próbaverzióra.

Ez a sablon tökéletes példája egy olyan folyamatnak, amelyet minden alkalommal követhet, amikor egy új vagy frissített kódrészletet szeretne telepíteni.

Egyértelmű lépéseket tartalmaz, amelyek végigvezetik a teljes telepítési folyamaton, a staging környezet beállításától a változtatások éles üzembe helyezéséig. Ezek a lépések gondoskodnak arról, hogy semmi se maradjon ki, és az egész folyamat minden egyes alkalommal zökkenőmentesen menjen végbe.

Ezt a sablont úgy terveztük, hogy útmutatóként szolgáljon az Ön számára megfelelő telepítési folyamat kialakításához. Minden vállalat más, minden szoftverprojekt más, és minden telepítési folyamat is más.

Szerkesztheti ezt a folyamatot, és hozzáadhatja az Ön, a vállalata és a projektje szempontjából releváns feladatokat.

Ez visszavezet a szoftverdokumentációhoz; a “szoftverdokumentációt” feladatként hozzáadhatja. Így mindenki, aki a szoftvertelepítési folyamaton dolgozik, emlékeztetve és ösztönözve lesz ennek elvégzésére, a folyamat részeként.

Van még néhány előre elkészített folyamatsablonom, amelyek hasznosak lehetnek az Ön számára, és amelyeket a bejegyzés végén mellékelek.

Mielőtt erre rátérnénk, nézzük meg, hol tárolhatja a szoftverdokumentációját.

Szoftverdokumentáció tárhelyének lehetőségei

Nem jó, ha csak egy csomó szöveges fájl él a számítógépén. A fejlesztők és a felhasználók számára elérhetőnek kell lenniük, amit nagy valószínűséggel úgy fogsz elérni, hogy a dokumentációkat az interneten tárolod, mivel ez nem az 1980-as évek.

Process Street (belső használatra)

Az új fejlesztők képzéséhez és a dokumentáció egy helyen való életben tartásához a Process Street egy jó választás a szoftverdokumentációhoz.

Először is létrehozhat egy folyamatot a dokumentáció megírásához, hogy biztosan megragadjon minden megfelelő részletet, és a lehető leghasznosabbá tegye azt.

A következő könnyen használható funkciókat használva ezután egyetlen helyen megírhatja és tárolhatja dokumentációját:

• Kép widgetek
• Szöveg widgetek
• Videó widgetek
• Fájl widgetek
• Subfeladatok
• Email widgetek
• Embed widgetek

A dokumentációjának Process Street-en belüli tárolása azt jelenti, hogy a vállalaton belül mindenki számára elérhető. Megoszthatja másokkal, elküldheti jóváhagyásra, emlékeztetőket állíthat be a felülvizsgálatra, és könnyen frissítheti.

Nézze meg:

Ha dokumentálható, akkor dokumentálható a Process Streetben.

Iratkozzon fel egy ingyenes próbaverzióra itt, és próbálja ki.

Read The Docs

Az, hogy a Read The Docs ingyenes, figyelemre méltó, ha látod, mi mindenre képes. A GitHubhoz hasonlóan annyi nyílt forráskódú anyagot hozhatsz létre, amennyit csak akarsz, ami nyíltan indexelve lesz az oldalon, de költséges lesz, ha a dokumentumokat priváttá és cégen belülivé akarod tenni. A mi céljainkhoz valószínűleg nem lesz gond, ha a felhasználók számára könnyen elérhetővé válnak a dokumentációk a weben.

A Read The Docs azért olyan jó, mert könnyedén importálhat dokumentációt bármely verziókezelő rendszerből, beleértve a Git, Mercurial, Subversion és Bazaar rendszereket is. Támogatja a webhookokat is, így a dokumentáció automatikusan elkészül, amikor kódot commitol.

Nézze meg a Kezdő útmutatót, hogy megismerje, hogyan működik, és hogyan viselkednek a dokumentációi, ha ott tárolja őket.

GitHub (& GitHub Pages)

Ha a GitHubot használja a szoftver verziókezelésére, akkor legalább egy README.MD fájl van az adattárban. Ha a GitHubot szeretnéd használni a szoftvered dokumentálására, ahogyan azt már több millióan tették a múltban, egyszerűen töltsd ki ezt a README fájlt markdownnal.

Egy nagyszerű példa erre sferik t repositoryja, itt látható képernyőfotó:

Ha nem csak egy lapnyi formázott szöveget szeretnél, kihasználhatod a GitHub Pages eszközét (minden GitHub-fiókhoz kapsz egy ingyenes weblapot + tárhelyet, és még egy egyéni domaint is átirányíthatsz hozzá). A Pages még remekül kinéző alapértelmezett témákkal is rendelkezik, amelyek professzionális megjelenést kölcsönöznek a dokumentációnak.

Fentebb az atom.io dokumentációja az Electronhoz a GitHubon hosztolva. Okos választás, mert automatikusan együttműködik a GitHub verziókezelőjével, akárcsak a többi szoftvered. Az oldal tárolóját itt találja.

Dropbox Paper (belső használatra)

A belső szoftverdokumentáció használatához a Dropbox Paper kiváló választás. Elődjéhez, a Hackpadhez hasonlóan, privát wikit hozhat létre vele az alkalmazottak számára. A dokumentumokat összekapcsolhatja egymással, kódblokkokat, képeket és oldalugrásokat illeszthet be, ahogyan azt bármelyik dokumentációs eszköztől megköveteli.

Amint a jobb oldali hozzászólásokból láthatja, a dokumentáció készítése során jóváhagyási folyamatokat és együttműködést is végezhet vele. Összességében ez egy nagyszerű eszköz a dokumentáció belső fejlesztésére és létrehozására, esetleg azzal a céllal, hogy később nyilvánosságra hozza, vagy csak belső használatra tartja meg.

Atlassian REST API Browser (API használatra)

Az Atlassian REST API Browser (RAB) alapértelmezés szerint benne van a JIRA Server, Confluence Server és Stash példányokban. A JIRA/Confluence környezetekben használható API-k felfedezésére készült, és egyben a dokumentáció tárhelye is. Ha természetesen az Ön API-ja megfelel ennek az eszköznek.

Dokumentálja API-ját ezzel az eszközzel, hogy JIRA/Confluence kompatibilis API-ja nagyobb nyilvánosságot kapjon. Nézd meg itt az Atlassian dokumentációját erről.

Tettra (belső használatra)

A Tettra egyfajta tudásbázis szoftver, ahol dokumentálhatod a fejlesztésedet, vagy egyáltalán bármit.

A Tettrát belsőleg használjuk a Process Streetnél egy csomó felhasználási esetre. Nap mint nap arra használom a Tettrát, hogy egyetlen helyen legyen az összes folyamatom dokumentálva, hogy soha ne felejtsem el, hogyan kapcsolódik egyik a másikhoz, vagy hogyan vannak beállítva a különböző automatizálások, amiket építettünk.

A Tettra nagyszerű, ha egyfajta könyvtárat szeretne létrehozni. Ez azt jelenti, hogy kiválóan alkalmas szoftverdokumentációhoz vagy akár csak a vállalat belső wikijeként.

Mivel a Tettra kifejezetten tudásmenedzsmentre készült, számos egyéb támogató funkcióval is rendelkezik. Például javaslatokat tud tenni arra vonatkozóan, hogy milyen extra tartalmakat vagy szakaszokat szeretne hozzáadni, hogy teljesebb képet adjon a szervezetéről és arról, hogy a dolgok hogyan illeszkednek egymáshoz.

Itt láthat egy kis videót arról, hogyan használhatja a Tettrát egy fejlesztőcsapat: & How Product & Engineering Teams Use Tettra.

Or, you can go here to read about how we use Tettra alongside Process Street: Munkafolyamatok és ellenőrzőlisták automatizálása: Process Street Case Study.

Check it out!

Apiary (for API use)

Az Apiary nem csak egy hely, ahol méhek élnek, hanem egy dedikált tárhely is az API dokumentáció számára. Írj markdownban, adj hozzá mock API-hívásokat, és az Apiary összeválogatja ezt olyasmivé, mint amit alább látsz:

Mindenki tesztelheti az API-t anélkül, hogy be kellene mennie az alkalmazásba vagy ténylegesen be kellene programoznia egy hívást, ami szuper hozzáférhetővé teszi az API megosztását, alapos dokumentálását, és dicsekedhet azzal, hogy mire képes.

Megbeszéltük, hogy hol tárolja a szoftver dokumentációját, most itt az ideje, hogy megvizsgáljuk, hogyan írja meg azt.

Szoftverdokumentáció-íróeszközök

A szoftverdokumentációt gyakran markdown nyelven írják, hogy lehetővé tegyék a hiperhivatkozásokat és a formázást, ugyanakkor egyszerű szöveg maradjon, hogy a verziókezelőben a kódfájlok mellett élhessen. Ez azt jelenti, hogy az általam választott íróeszközök közül sokan egyszerű markdown-szerkesztőket választanak, amelyek élvezetessé teszik az írás élményét. Emellett van néhány nagyon hatékony, nem markdown-alapú megoldás is.

MarkdownPad (Windows)

A MarkdownPad ingyenes és prémium verzióval – mindkettő rengeteg nagyszerű funkcióval – a legnépszerűbb markdown-szerkesztő Windowsra. Blogbejegyzésekhez, weboldalakhoz, cikkekhez, README-khez és természetesen szoftverdokumentációhoz optimalizált.

A MarkdownPad ingyenesen, vagy a prémium verzió 14,95 dollárért szerezhető be.

iA Writer (Mac)

Az iA Writer egy egyszerű, gyönyörű markdown-szerkesztő, könyvtárfunkcióval, ami azt jelenti, hogy az oldalsávban könnyen visszautalhat más dokumentumokra. Hiányoznak belőle a dokumentumok közötti belső hivatkozások, ahogy az elvárható lenne egy szoftverdokumentációban, de ezeket bármikor pótolhatod, ha már végleges formában van (vagyis ha az internetre kerül egy webhelyen).

Ha az egész dokumentációt egyetlen, széttagolt oldalra írod, használhatsz oldalugrási horgonyokat, hogy segítsd a felhasználóknak a navigációt.

Az iA Writer 9,99 dollárba kerül a Mac App Store-ból.

ProProfs Knowledge Base

AProfs Knowledge Base egy fantasztikus kis eszköz a dokumentumkészítés minden szakaszához; az írástól és szerkesztéstől kezdve a testreszabáson át a munkafolyamatok beállításáig és a közzétételig. Multimédiát adhat hozzá, meglévő tartalmat importálhat word-dokumentumokból, PDF-ekből vagy PPT-kből, a dokumentum több változatát mentheti, és szükség esetén visszaállíthatja azokat.

Az eszköz igazi szépsége azonban a használhatóságában rejlik. Bárki és bárki használhatja szoftverdokumentáció készítésére. Akár évek óta dokumentálsz szoftvereket, akár csak nemrég kezdted el, ez egy hihetetlenül egyszerű és könnyen használható eszköz.

AProfs ingyenesen használható, vagy frissíthetsz a prémium csomagra, ami havonta 112 dollárba kerül.

SimpleMDE (böngésző)

Míg technikailag bármilyen szövegszerkesztőben lehet markdownt írni, mert ez egy módja a sima szöveg formázásának, nem pedig szigorúan egy “eszköz”, nem fog meglepni, hogy a böngészőben is lehetséges! A SimpleMDE egyrészt egy JavaScriptre épülő, funkcionális markdown szerkesztő, másrészt egy nyílt forráskódú projekt, amelyből tanulhatsz, és szükség esetén saját használatra adaptálhatod.

A SimpleMDE 100%-ban ingyenes! A forrást a GitHubon itt találod.

reStructuredText szerkesztők

A Markdown az egyik a két leggyakrabban használt nyelv közül a szoftverdokumentáció írásához, de van egy másik, amelyet eddig nem vizsgáltunk, és ez a reStructuredText. Nagyon hasonlít a markdownhoz, de érdemes megtanulni szoftverdokumentációs célokra.

A reStructuredText készítője, a Docutils összeállított egy listát a reStructuredText szerkesztőkről itt, amely tartalmazza a következőket:

A reStructuredText lényege, hogy könnyen konvertálható a különböző formátumok között, különösen egyszerű szövegből egy statikus weboldalba. További infókat itt találsz.

A forráskódból automatikusan dokumentációt generáló eszközök

A dokumentációban semmi sem ér fel az emberi kézzel (ez jól látszik a Slack és a Giphy dokumentációjában, hogy csak néhányat említsünk). Azonban kiindulási pontként (különösen hatalmas forráskódú könyvtárak esetében) a legjobb, ha a vázdokumentációt automatikusan generáljuk. Ez a forrás függvényeinek és kommentjeinek elemzésével működik, és nyelvtől függően van néhány különböző lehetőség:

Mielőtt kizárólag az automatikus generálásra hagyatkozna, javaslom, hogy olvassa el ezt a StackExchange témát, amely mérlegeli az előnyöket és hátrányokat.

Végszavak a szoftverdokumentációról

Megannyi flancos megoldás, gyorsjavítás és eszköz létezik, amelyek (őszintén szólva) majdnem azonosak. Ami végül is számít, az

Ami a legfontosabb, az végül is az, hogy:

a) minden egyes szoftverhez, amit készítesz, szoftverdokumentációt írsz
b) átfogóan írod meg, és valahol elhelyezed, ahol a felhasználó hozzáférhet

Előtte már említettem, hogy van még néhány fejlesztési folyamat sablonom, amit talán szívesen megnéznél?

Nos, itt vannak…

Process Street fejlesztési folyamat sablonok

Mielőtt átadnám ezeket a sablonokat, hadd magyarázzam el egy kicsit jobban, mi is az a Process Street.

Szóval tudjuk, hogy a Process Street egy szupererős ellenőrzőlista. Ez egy olyan szoftver, amely segít a folyamatok létrehozásában és kezelésében.

De várjunk csak, a Process Street ennél többről szól!

Nézze meg ezt a bemutatkozó videót, hogy megtudja, mire gondolok:

Szóval, mint látja, nem csak egy fejlesztési folyamatsablont hozhat létre, és ebből futtathatja le az egyes ellenőrző listákat minden alkalommal, amikor a fejlesztési folyamatot le kell zárnia, hanem testre szabhatod az alábbi extra funkciók segítségével

• Feladatok leállítása
• Dinamikus esedékességi időpontok
• Feladatengedélyek
• Feltételes logika
• Elismerési feladatok
• Embed widget
• Rólazonosítás

Feladatok kiosztása, jóváhagyást kaphat, érvényesítheti a feladatok elvégzésének sorrendjét, és a folyamatot Zapier, webhooks vagy API integráción keresztül több ezer alkalmazáshoz kapcsolhatja.

Nézze meg ezt a webináriumot a legújabb funkcióinkról, és nézze meg, hogyan hozhatja ki belőlük a legtöbbet:

Mindezek tudatában tekintse meg az alábbi, előre elkészített sablonokat:

Hálózatbiztonsági audit ellenőrzési lista

Ezt a sablont egy kockázatkezelő vagy azzal egyenértékű informatikai szakember használhatja a hálózat biztonsági sebezhetőségének felmérésére.

A hálózatbiztonsági audit ellenőrzési lista eléréséhez kattintson ide!

Havi honlap karbantartási ellenőrzőlista

Ezt a havi honlap karbantartási ellenőrzőlistát használhatja a webhely betöltési sebességének optimalizálására, a sebezhetőségek keresésére és a keresési láthatóság felülvizsgálatára.

Kattintson ide a Havi honlap karbantartási ellenőrzőlista eléréséhez!

Szoftvertesztelési útmutató

Ez a folyamat használható egy teljes szoftverfejlesztési projekt kezeléséhez az elejétől a végéig, beleértve a tervezést, az ügyfélkezelést és a bevezetés utáni ellenőrzéseket is.

Kattintson ide a Szoftvertesztelés oktatóanyag eléréséhez!

És ezzel meg is van.

Most már szabadon használhatja azt, ami megkönnyíti az életét. Remélem, ebben a listában megtalálod az új kedvenc eszközödet.