18 verktyg för mjukvarudokumentation som gör det hårda arbetet för dig

🟢 Bonusmaterial: Git Workflow Checklist to simplify & streamline version management

Och utan dokumentation är programvara bara en svart låda. Och svarta lådor är inte alls lika användbara som de skulle kunna vara eftersom deras inre funktioner är dolda för dem som behöver dem öppet.

Mjukvarudokumentation förvandlar din programvara till en glaslåda genom att förklara för användare och utvecklare hur den fungerar eller används.

Du har förmodligen sett dokumentation tidigare, men om du behöver en uppfräschning, här är ett exempel från Slacks API:

Som du kan se förklarar Slack allt om sitt API i outhärdliga detaljer. Alla relaterade sidor är länkade, det finns en sidofält med lättåtkomliga ämnen och skärmdumpar av vad användaren kan förvänta sig att se.

För att förklara detta mer i detalj kommer vi att täcka följande ämnen i det här inlägget om Process Street:

• Vad är programvarudokumentation?
• Hostingalternativ för programvarudokumentation
• Skrivverktyg för programvarudokumentation
• Slutord om programvarudokumentation

Vi sätter igång.

Vad är programvarudokumentation?

”Documentation in software engineering is the umbrella term that encompasses all written documents and materials dealing with a software product’s development and use” – Prototype.io, Software Documentation Types and Best Practices

Alla programvaror bör ha någon form av dokumentation som i detalj förklarar vad produkten är, hur den fungerar och varför den fungerar på det sättet.

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

Som utvecklare är ditt främsta mål att skriva den bästa koden du kan. Du vill att din kod ska vara bäst i klassen, lätt att läsa, lätt att använda och du vill att bra saker ska hända som ett resultat av den. Eller hur?

Men utan att dokumentera vad du har gjort och varför du har gjort det:

• Ingen annan än du kan använda din kod

Och utan dokumentation kommer ingen att förstå vad du har gjort och varför du har gjort det. Det blir otroligt svårt, näst intill omöjligt, för någon annan att plocka upp din kod och arbeta med den. De kanske till och med skrotar den och börjar om från början, eftersom det i vissa fall går snabbare än att försöka förstå vad du har gjort och varför.

• Du kan inte uppdatera eller förbättra den

Kan du komma ihåg vad du åt till middag i lördags för tre månader sedan? Om du inte är en vanemänniska är chansen stor att du inte kan det. Så det är rimligt att säga att du förmodligen inte kommer att komma ihåg den kod du skrev, två, tre, fyra månader efter att du gjorde den. Om du inte kan komma ihåg skälen bakom dina kodbeslut kommer du att ha svårt att kunna uppdatera eller förbättra den.

Trots detta är programvarudokumentation ofta en uppgift som skyndas på, görs dåligt, bortprioriteras eller helt glöms bort.

Innan vi börjar prata om vilka verktyg du kan använda för att skriva programvarudokumentation måste vi fundera på ett sätt att se till att uppgiften överhuvudtaget blir gjord.

Det är här Process Street kan hjälpa till.

Process Street är en programvara för hantering av affärsprocesser (BPM) som kan användas för att skapa, hantera och följa processer.

Mer om vad Process Street är senare, men låt mig för tillfället visa dig hur du kan använda det som ett verktyg för att hjälpa dig att få in programvarudokumentation i varje programvaruutvecklingsprojekt du arbetar med.

Nedan följer ett exempel på en förtillverkad mall för en process för programvaruimplementering. Den här mallen skapades för att hjälpa programvaruingenjörer och programmerare att distribuera sin programvara på bästa möjliga sätt.

Klicka här för att få tillgång till Software Deployment Process!

För att få den här mallen kan du antingen logga in och lägga till den i din instrumentpanel eller registrera dig för en gratis provperiod.

Den här mallen är ett perfekt exempel på en process som du kan följa varje gång du vill distribuera en ny eller uppdaterad kod.

Den har tydliga steg som guidar dig genom hela distributionsprocessen, från att ställa in en staging-miljö till att sätta dina ändringar live. Dessa steg ser till att inget missas och att hela processen går smidigt varje gång.

Vi har utformat den här mallen så att den kan användas som en guide för att hjälpa dig att skapa en distributionsprocess som fungerar för dig. Varje företag är annorlunda, varje programvaruprojekt är annorlunda och varje distributionsprocess är annorlunda.

Du kan redigera den här processen och lägga till de uppgifter som är relevanta för dig, ditt företag och ditt projekt.

Det för mig tillbaka till programvarudokumentation; du kan lägga till ”programvarudokumentation” som en uppgift. På så sätt kommer alla som arbetar med programvaruimplementeringsprocessen att påminnas och uppmuntras att slutföra detta, som en del av processen.

Jag har några fler färdiga processmallar som kan vara till nytta för dig och som jag lägger till i slutet av det här inlägget.

Innan vi kommer till det, ska vi titta på var du kan lagra din programvarudokumentation.

Hostingalternativ för programvarudokumentation

Det är inte bra att bara ha en massa textfiler som bor på din dator. De måste vara tillgängliga för utvecklare och användare, vilket du med största sannolikhet kommer att göra genom att hosta dokumentationen på internet eftersom det inte är 1980-talet.

Process Street (för internt bruk)

För att utbilda nya utvecklare och för att hålla dokumentationen levande på samma ställe är Process Street ett bra val för programvarudokumentation.

Först kan du skapa en process för att skriva din dokumentation, för att se till att du fångar in alla rätt detaljer och gör den så användbar som möjligt.

Med hjälp av följande lättanvända funktioner kan du sedan skriva och lagra din dokumentation på ett enda ställe:

• Bildwidgetar
• Textwidgetar
• Video-widgetar
• Filwidgetar
• Subuppgifter
• E-postwidgetar
• Embed widgets

Lagring av din dokumentation i Process Street innebär att den är tillgänglig för alla i företaget. Du kan dela den med andra, skicka den för godkännande, ställa in påminnelser för att granska den och uppdatera den enkelt.

Kontrollera den:

Om det kan dokumenteras så kan det dokumenteras i Process Street.

Anslut dig till en gratis provperiod här och testa det.

Read The Docs

Det är anmärkningsvärt att Read The Docs är gratis när man ser allt som det kan göra. I likhet med GitHub kan du skapa så mycket material med öppen källkod du vill som blir öppet indexerat på webbplatsen, men det kommer att kosta dig om du vill göra dokumenten privata och interna för ditt företag. För våra syften är det troligt att du kommer att vara nöjd med att ha dokumentationen lätt tillgänglig för användare på webben.

Anledningen till att Read The Docs är så bra är att du utan ansträngning kan importera dokumentation från vilket versionskontrollsystem som helst, inklusive Git, Mercurial, Subversion och Bazaar. Den har också stöd för webhooks så att dokumentationen byggs automatiskt när du lägger in kod.

Kontrollera deras Getting Started-guide för att få en känsla för hur den fungerar och hur din dokumentation skulle bete sig när den är värd där.

GitHub (& GitHub Pages)

Om du använder GitHub för att hantera versionskontrollen av din programvara har du, som ett minimum, en README.MD-fil i repositoriet. Om du vill använda GitHub för att dokumentera din programvara, som miljontals andra har gjort tidigare, är det bara att fylla den README-filen med markdown.

Ett bra exempel är sferiks t-repositorium, skärmdumpat här:

Om du vill ha mer än bara ett ark med formaterad text kan du dra nytta av GitHubs Pages-verktyg (du får en gratis webbsida + webbhotell med varje GitHub-konto, och du kan till och med dirigera en egen domän till den). Pages har till och med snygga standardteman som får din dokumentation att se professionell ut.

Ovan är atom.io-dokumentationen för Electron som finns på GitHub. Det är ett smart val eftersom den automatiskt fungerar med GitHubs versionskontroll, precis som resten av din programvara. Se webbplatsens arkiv här.

Dropbox Paper (för internt bruk)

För intern dokumentation av programvara är Dropbox Paper ett utmärkt val. Precis som föregångaren Hackpad kan du använda den för att skapa en privat wiki för anställda. Du kan länka ihop dokument, infoga kodblock, bilder och sidhopp, precis som du kräver av alla dokumentationsverktyg.

Som du kan se i kommentarerna till höger kan du också använda den för att gå igenom godkännandeprocesser och samarbeta kring skapandet av dokumentation. På det hela taget är det ett utmärkt verktyg för att internt utveckla och skapa dokumentation, kanske med sikte på att publicera den senare, eller bara behålla den för internt bruk.

Atlassian REST API Browser (för API-användning)

Atlassians REST API Browser (RAB) ingår som standard i JIRA Server, Confluence Server och Stash-instanser. Den är byggd för att upptäcka API:er som är tillgängliga för användning i JIRA/Confluence-miljöer, och även en plats för att vara värd för din dokumentation. Om ditt API förstås passar in på listan.

Dokumentera ditt API med det här verktyget för att ge ditt JIRA/Confluence-kompatibla API mer exponering. Kolla här för Atlassians dokumentation om hur du gör det.

Tettra (för internt bruk)

Tettra är en slags kunskapsbasprogramvara där du kan dokumentera din utveckling, eller vad som helst överhuvudtaget.

Vi använder Tettra internt på Process Street för ett gäng användningsfall. Till vardags använder jag Tettra för att ha en enda plats där alla mina processer är dokumenterade, så att jag aldrig glömmer hur den ena hänger ihop med den andra eller hur de olika automatiseringarna som vi har byggt har ställts in.

Tettra är bra om du vill skapa ett bibliotek av något slag. Det betyder att det är lysande för programvarudokumentation eller till och med bara som en intern wiki för ditt företag.

Med tanke på att Tettra är särskilt utformat för kunskapshantering har det också en mängd andra stödfunktioner. Den kan till exempel ge förslag på vilket extra innehåll eller vilka sektioner du vill lägga till för att ge en mer komplett bild av din organisation och hur saker och ting passar ihop.

Du kan se en liten video här för hur ett utvecklingsteam skulle kunna använda Tettra: Du kan också gå hit för att läsa om hur vi använder Tettra tillsammans med Process Street: Automatisering av arbetsflöden och checklistor: Process Street Case Study.

Kolla in!

Apiary (för API-användning)

Apiary är inte bara en plats där bin bor, utan också en särskild värd för API-dokumentation. Skriv i markdown, lägg till mock API-anrop och Apiary sammanställer det till något som du ser nedan:

Alla kan testa API:et utan att behöva gå in i appen eller faktiskt programmera ett anrop, vilket gör det till ett mycket lättillgängligt sätt att dela med sig av ditt API, dokumentera det i detalj och skryta om vad det kan göra.

Vi har diskuterat var du ska lagra din programvarudokumentation, nu är det dags att titta på hur du skriver den.

Skrivverktyg för programvarudokumentation

Programvarudokumentation skrivs ofta i markdown för att möjliggöra hyperlänkar och formatering samtidigt som den hålls i ren text så att den kan leva tillsammans med kodfilerna i versionskontrollen. Det innebär att många av mina val av skrivverktyg är enkla markdown-redigerare som gör skrivandet trevligt. Dessutom finns det också ett par mycket effektiva icke-markdown-lösningar inlagda där.

MarkdownPad (Windows)

Med en gratis- och en premiumversion – båda med massor av bra funktioner – är MarkdownPad den mest populära markdown-redigeraren för Windows. Den är optimerad för blogginlägg, webbplatser, artiklar, READMEs och naturligtvis programvarudokumentation.

Du kan få MarkdownPad gratis eller skaffa premiumversionen för 14,95 dollar.

iA Writer (Mac)

iA Writer är en enkel och snygg markdown-redigerare med en biblioteksfunktion som innebär att du enkelt kan hänvisa tillbaka till andra dokument i sidofältet. Den saknar interna länkar mellan dokumenten som du förväntar dig i programvarudokumentation, men du kan alltid göra ett pass på dessa när den är i sin slutliga form (det vill säga om den ska hamna på internet i en webbplats).

Om du skriver hela dokumentationen på en enda uppdelad sida kan du använda sidhoppningsankare för att hjälpa användarna att navigera.

iA Writer kostar 9,99 dollar från Mac App Store.

ProProfs Knowledge Base

Profs Knowledge Base är ett fantastiskt litet verktyg för alla stadier av dokumentskapande; från skrivning och redigering till anpassning, fastställande av arbetsflöden och publicering. Du kan lägga till multimedia, importera befintligt innehåll från Word-dokument, PDF eller PPT, spara flera versioner av dokumentet och återställa dem vid behov.

Men det verkligt fina med det här verktyget ligger i dess användbarhet. Vem som helst och alla kan använda det för att bygga programvarudokumentation. Oavsett om du har dokumenterat programvara i flera år eller nyligen har börjat, är det ett otroligt enkelt och lättanvänt verktyg.

ProProfs är gratis att använda, eller så kan du uppgradera till premiumpaketet som kostar 112 dollar per månad.

SimpleMDE (webbläsare)

Som du tekniskt sett kan skriva markdown i vilken textredigerare som helst, eftersom det är ett sätt att formatera vanlig text, och inte i egentlig mening ett ”verktyg”, så kommer det inte att förvåna dig att det också går att skriva markdown i din webbläsare! SimpleMDE är både en funktionell markdown-redigerare byggd på JavaScript och ett projekt med öppen källkod som du kan lära dig av och anpassa för ditt eget bruk, om det behövs.

SimpleMDE är 100 % gratis! Hämta källkoden på GitHub här.

reStructuredText-redigerare

Markdown är ett av de två vanligaste språken för att skriva programvarudokumentation, men det finns ett annat språk som vi inte har tittat på hittills, och det är reStructuredText. Det är mycket likt markdown, men värt att lära sig för programvarudokumentation.

Docutils, skaparen av reStructuredText, har sammanställt en lista över reStructuredText-redigerare här, som inkluderar:

Punkten med reStructuredText är att det är lätt att konvertera mellan olika format, särskilt från vanlig text till en statisk webbplats. Se mer information här.

Verktyg för att automatiskt generera dokumentation från källkod

Det finns inget som den mänskliga kontakten när det gäller dokumentation (det är tydligt i dokumentationen för Slack och Giphy, för att nämna ett par). Som utgångspunkt (särskilt för stora källkodsbibliotek) är det dock bäst att generera skelettdokumentationen automatiskt. Detta arbete genom att analysera källans funktioner och kommentarer, och det finns några olika alternativ beroende på språk:

Innan du går vidare och enbart förlitar dig på automatisk generering föreslår jag att du läser denna StackExchange-tråd som väger för- och nackdelar.

Slutord om programvarudokumentation

Det finns gott om tjusiga lösningar, snabba lösningar och verktyg som (helt ärligt) är nästan identiska. Vad som betyder något i slutändan är att

Vad som betyder mest, i slutändan, är att:

a) du skriver programvarudokumentation för varje programvara du bygger
b) du skriver den utförligt och lägger upp den någonstans som användaren kan komma åt

Jag nämnde tidigare att jag hade några fler mallar för utvecklingsprocessen som du kanske skulle vilja kolla in?

Ja, här är de…

Process Street utvecklingsprocessmallar

Innan jag ger dig dessa mallar, låt mig förklara vad Process Street är lite mer.

Så vi vet att Process Street är superkraftfulla checklistor. Det är en programvara som hjälper dig att skapa och hantera processer.

Men vänta, det finns mer än så i Process Street!

Se den här introvideon för att ta reda på vad jag menar:

Så du ser, du kan inte bara skapa en mall för utvecklingsprocessen och köra individuella checklistor från denna varje gång du behöver slutföra utvecklingsprocessen, utan du kan också anpassa den med hjälp av dessa extra funktioner

• Stoppa uppgifter
• Dynamiska förfallodagar
• Taskbehörigheter
• Villkorlig logik
• Godkännandeuppgifter
• Embed widget
• Rolltilldelningar

Ansätt uppgifter, få godkännande, tvinga fram en ordning som uppgifterna ska utföras i, och du kan ansluta processen till tusentals appar via Zapier, webhooks eller API-integration.

Se det här webbseminariet om våra nyaste funktioner och se hur du kan få ut det mesta av dem:

Med allt detta i åtanke kan du ta en titt på nedanstående färdiga mallar:

Checklista för granskning av nätverkssäkerheten

Den här mallen kan användas av en riskhanterare eller motsvarande IT-proffs för att bedöma ett nätverk med avseende på säkerhetssårbarheter.

Klicka här för att komma åt checklistan för granskning av nätverkssäkerheten!

Controllista för månatligt underhåll av webbplats

Använd den här checklistan för månatligt underhåll av webbplats för att optimera webbplatsens laddningshastighet, söka efter sårbarheter och se över din sökbarhet.

Klicka här för att få tillgång till checklistan för månatligt underhåll av webbplats!

Tutorial för testning av mjukvara

Den här processen kan användas för att hantera ett helt projekt för utveckling av mjukvara från början till slut, inklusive design, hantering av klienter och även kontroller efter lanseringen.

Klicka här för att få tillgång till handledningen i programvarutestning!

Och där har du det.

Du är nu fri att använda det som gör ditt liv enklare. Jag hoppas att du hittar ditt nya favoritverktyg i den här listan.