18 softwaredokumentationsværktøjer, der gør det hårde arbejde for dig

🟢 Bonusmateriale: Git Workflow Checkliste til at forenkle & strømline versionsstyring

Og uden dokumentation er software bare en sort boks. Og sorte bokse er ikke nær så nyttige, som de kunne være, fordi deres indre funktioner er skjult for dem, der har brug for dem i det fri.

Softwaredokumentation gør din software til en glasboks ved at forklare brugere og udviklere, hvordan den fungerer eller bruges.

Du har sikkert set dokumentation før, men hvis du har brug for en genopfriskning, er her et eksempel fra Slacks API:

Som du kan se, forklarer Slack alt om sit API i ulidelige detaljer. Der er linket til alle relaterede sider, der er en sidebar med lettilgængelige emner og skærmbilleder af, hvad brugeren kan forvente at se.

For at forklare dette mere detaljeret vil vi dække følgende emner i dette indlæg i Process Street:

• Hvad er softwaredokumentation?
• Muligheder for hosting af softwaredokumentation
• Skrivværktøjer til softwaredokumentation
• Slutord om softwaredokumentation

Lad os komme i gang.

Hvad er softwaredokumentation?

“Dokumentation inden for software engineering er et paraplybegreb, der omfatter alle skriftlige dokumenter og materialer, der omhandler et softwareprodukts udvikling og brug.” – Prototype.io, Software Documentation Types and Best Practices

Alle stykker software bør have en eller anden form for dokumentation, der i detaljer forklarer, hvad produktet er, hvordan det fungerer, og hvorfor det fungerer på den måde.

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

Som udvikler er dit hovedformål at skrive den bedste kode, du overhovedet kan. Du ønsker, at din kode skal være bedst i klassen, let at læse, let at bruge, og du ønsker, at der skal ske gode ting som resultat af den. Ikke sandt?

Men uden at dokumentere, hvad du har gjort, og hvorfor du har gjort det:

• Ingen anden end dig kan bruge din kode

Og uden dokumentation er der ingen, der forstår, hvad du har gjort, og hvorfor du har gjort det. Det vil være utroligt svært, nærmest umuligt, for en anden at samle din kode op og arbejde videre med den. De vil måske endda skrotte den og starte forfra, da det i nogle tilfælde vil være hurtigere end at forsøge at regne ud, hvad du har gjort og hvorfor.

• Du kan ikke opdatere eller forbedre den

Kan du huske, hvad du spiste til middag i lørdags for tre måneder siden? Medmindre du er et komplet vanedyr, er der stor sandsynlighed for, at du ikke kan det. Så det er rimeligt at sige, at du sandsynligvis ikke vil kunne huske den kode, du har skrevet, to, tre, fire måneder efter, at du har lavet den. Hvis du ikke kan huske årsagerne bag dine kodningsbeslutninger, vil du have svært ved at kunne opdatere eller forbedre den.

På trods af dette er softwaredokumentation ofte en opgave, der bliver forhastet, udført dårligt, nedprioriteret eller helt glemt.

Hvor vi begynder at tale om, hvilke værktøjer du kan bruge til at skrive softwaredokumentation, er vi nødt til at tænke på en måde at sikre, at opgaven overhovedet bliver udført.

Det er her, Process Street kan hjælpe.

Process Street er et stykke software til forretningsprocesstyring (BPM), der kan bruges til at oprette, administrere og følge processer.

Mere om hvad Process Street er senere, men lad mig nu vise dig, hvordan du kan bruge det som et værktøj til at hjælpe dig med at få softwaredokumentation ind i hvert eneste softwareudviklingsprojekt, du arbejder på.

Nedenfor er der et eksempel på en færdiglavet skabelon for en softwareimplementeringsproces. Denne skabelon blev skabt for at hjælpe softwareingeniører og programmører med at implementere deres software på den bedst mulige måde.

Klik her for at få adgang til Software Deployment Process!

For at få denne skabelon skal du enten logge ind og tilføje den til dit instrumentbræt, eller tilmelde dig en gratis prøveperiode.

Denne skabelon er et perfekt eksempel på en proces, som du kan følge, hver gang du ønsker at implementere et nyt eller opdateret stykke kode.

Den har klare trin, der guider dig gennem hele udrulningsprocessen, fra opsætning af et staging-miljø til at sætte dine ændringer live. Disse trin vil sikre, at intet bliver overset, og at hele processen går glat hver eneste gang.

Vi har designet denne skabelon til at blive brugt som en vejledning til at hjælpe dig med at skabe en implementeringsproces, der fungerer for dig. Alle virksomheder er forskellige, alle softwareprojekter er forskellige, og alle implementeringsprocesser er forskellige.

Du kan redigere denne proces og tilføje de opgaver, der er relevante for dig, din virksomhed og dit projekt.

Hvilket bringer mig tilbage til softwaredokumentation; du kunne tilføje “softwaredokumentation” som en opgave. På den måde vil alle, der arbejder gennem softwareimplementeringsprocessen, blive mindet om og opfordret til at gennemføre dette, som en del af processen.

Jeg har et par flere færdiglavede processkabeloner, som måske kan være nyttige for dig, og som jeg vil inkludere i slutningen af dette indlæg.

Hvor vi kommer til det, skal vi se på, hvor du kan opbevare din softwaredokumentation.

Muligheder for hosting af softwaredokumentation

Det er ikke godt at have bare en masse tekstfiler liggende på din computer. De skal være tilgængelige for udviklere og brugere, hvilket du højst sandsynligt vil gøre ved at hoste dokumentationen på internettet, da det ikke er 1980’erne.

Process Street (til internt brug)

For at uddanne nye udviklere og holde din dokumentation levende på samme sted, er Process Street et solidt valg til softwaredokumentation.

Først kan du oprette en proces til at skrive din dokumentation, så du sikrer dig, at du fanger alle de rigtige detaljer og gør den så brugbar som muligt.

Ved hjælp af følgende brugervenlige funktioner kan du derefter skrive og gemme din dokumentation ét enkelt sted:

• Billedwidgets
• Tekstwidgets
• Video widgets
• Fil widgets
• Subopgaver
• Email widgets
• Embed widgets

Lagerer du din dokumentation i Process Street, kan den tilgås af alle i virksomheden. Du kan dele den med andre, sende den til godkendelse, indstille påmindelser om at gennemgå den og nemt opdatere den.

Tjek det ud:

Hvis det kan dokumenteres, kan det dokumenteres i Process Street.

Amelder dig til en gratis prøveperiode her, og prøv det af.

Read The Docs

Det er bemærkelsesværdigt, at Read The Docs er gratis, når man ser alt det, det kan gøre. I lighed med GitHub kan du oprette så meget open source-materiale, som du vil, der bliver åbent indekseret på webstedet, men det kommer til at koste dig, hvis du vil gøre dokumenterne private og interne for din virksomhed. Til vores formål vil du sandsynligvis være tilfreds med, at dokumentationen er let tilgængelig for brugerne på nettet.

Grunden til, at Read The Docs er så god, er, at du uden besvær kan importere dokumentation fra ethvert versionskontrolsystem, herunder Git, Mercurial, Subversion og Bazaar. Den understøtter også webhooks, så dokumentationen bliver bygget automatisk, når du committerer kode.

Kig i deres Getting Started-guide for at få en fornemmelse af, hvordan den fungerer, og hvordan din dokumentation vil opføre sig, når den er hostet der.

GitHub (& GitHub Pages)

Hvis du bruger GitHub til at administrere versionskontrol for din software, har du som minimum en README.MD-fil i repositoryet. Hvis du vil bruge GitHub til at dokumentere din software, som millioner af andre har gjort tidligere, skal du blot udfylde denne README-fil med markdown.

Et godt eksempel er sferiks t-repository, som er screenshotet her:

Hvis du vil have mere end blot et ark med formateret tekst, kan du udnytte GitHubs Pages-værktøj (du får en gratis webside + hosting med hver GitHub-konto, og du kan endda dirigere et brugerdefineret domæne til den). Pages har endda flotte standardtemaer, der får din dokumentation til at se professionel ud.

Ovenfor er atom.io-dokumentationen for Electron hostet på GitHub. Det er et smart valg, fordi det automatisk fungerer med GitHubs versionskontrol, ligesom resten af din software. Se webstedets repository her.

Dropbox Paper (til intern brug)

Til intern brug af softwaredokumentation er Dropbox Paper et glimrende valg. Ligesom forgængeren Hackpad kan du bruge den til at oprette en privat wiki for medarbejderne. Du kan linke dokumenter sammen, indsætte kodeblokke, billeder og sidespring, ligesom du ville kræve det af ethvert dokumentationsværktøj.

Som du kan se af kommentarerne til højre, kan du også bruge det til at gennemgå godkendelsesprocesser og samarbejde om oprettelsen af dokumentation. Alt i alt er det et godt værktøj til intern udvikling og oprettelse af dokumentation, måske med henblik på at offentliggøre den senere, eller bare beholde den til internt brug.

Atlassian REST API Browser (til API-brug)

Atlassians REST API Browser (RAB) er som standard inkluderet i JIRA Server, Confluence Server og Stash-instanser. Den er bygget til at opdage API’er, der er tilgængelige til brug i JIRA/Confluence-miljøer, og den er også et sted at hoste din dokumentation. Hvis din API selvfølgelig passer ind i billedet.

Dokumenter din API ved hjælp af dette værktøj for at give din JIRA/Confluence-kompatible API mere eksponering. Se her for Atlassians dokumentation om hvordan du gør det.

Tettra (til internt brug)

Tettra er en slags vidensbasissoftware, hvor du kan dokumentere din udvikling, eller hvad som helst.

Vi bruger Tettra internt hos Process Street til en masse use cases. Til dagligt bruger jeg Tettra til at have et enkelt sted, hvor alle mine processer er dokumenteret, så jeg aldrig glemmer, hvordan den ene hænger sammen med den anden, eller hvordan de forskellige automatiseringer, vi har bygget, er blevet sat op.

Tettra er fantastisk, hvis du ønsker at oprette en slags bibliotek. Det betyder, at det er genialt til softwaredokumentation eller endda bare som en intern wiki for din virksomhed.

Da Tettra er specielt designet til vidensstyring, leveres det også med et væld af andre understøttende funktioner. For eksempel kan den komme med forslag til, hvilket ekstra indhold eller sektioner du måske vil tilføje for at give et mere komplet billede af din organisation, og hvordan tingene hænger sammen.

Du kan se en lille video her for, hvordan et udviklerteam kan se ud til at bruge Tettra: Sådan bruger Product & Engineering Teams Tettra.

Og du kan gå her for at læse om, hvordan vi bruger Tettra sammen med Process Street: Automatisering af arbejdsgange og tjeklister: Process Street Case Study.

Kig på det!

Apiary (til API-brug)

Som et sted, hvor bierne bor, er Apiary også en dedikeret vært for API-dokumentation. Skriv i markdown, tilføj mock API-kald, og Apiary samler det til noget, som du ser nedenfor:

Alle kan teste API’et uden at skulle gå ind i appen eller faktisk programmere et kald, hvilket gør det til en supertilgængelig måde at dele dit API på, dokumentere det i dybden og prale af, hvad det kan gøre.

Vi har diskuteret, hvor du skal gemme din softwaredokumentation, nu er det tid til at se på, hvordan du skal skrive den.

Skrivværktøjer til softwaredokumentation

Softwaredokumentation skrives ofte i markdown for at give mulighed for hyperlinks og formatering, samtidig med at det forbliver ren tekst, så det kan leve sammen med kodefilerne i versionsstyring. Det betyder, at mange af mine valg af skriveværktøjer er enkle markdown-redigeringsprogrammer, der gør skriveoplevelsen behagelig. Derudover er der også smidt et par meget effektive ikke-markdown-løsninger ind.

MarkdownPad (Windows)

Med en gratis og en premium-version – begge med et væld af gode funktioner – er MarkdownPad den mest populære markdown-editor til Windows. Den er optimeret til blogindlæg, websites, artikler, README’er og selvfølgelig softwaredokumentation.

Du kan få MarkdownPad gratis eller få premium-versionen til 14,95 $.

iA Writer (Mac)

iA Writer er en enkel og smuk markdown-editor med en biblioteksfunktion, der betyder, at du nemt kan referere tilbage til andre dokumenter i sidebaren. Den mangler interne links mellem dokumenterne, som man forventer, at der er i softwaredokumenter, men du kan altid lave en overhaling af disse, når den er i sin endelige form (dvs. hvis den skal ende på internettet på et websted).

Hvis du skriver hele din dokumentation på én opsplittet side, kan du bruge sidehop-ankre for at hjælpe brugerne med at navigere.

iA Writer koster 9,99 dollars i Mac App Store.

ProProfs Knowledge Base

Profs Knowledge Base er et fantastisk lille værktøj til alle faser af dokumentoprettelsen; fra skrivning og redigering til tilpasning, indstilling af arbejdsgange og udgivelse. Du kan tilføje multimedier, importere eksisterende indhold fra Word-dokumenter, PDF-filer eller PPT-filer, gemme flere versioner af dokumentet og gendanne dem, når det er nødvendigt.

Men den virkelige skønhed ved dette værktøj ligger i dets anvendelighed. Alle og enhver kan bruge det til at udarbejde softwaredokumentation. Uanset om du har dokumenteret software i årevis eller først for nylig er begyndt, er det et utroligt simpelt og letanvendeligt værktøj.

Profs er gratis at bruge, eller du kan opgradere til premium-pakken, som koster 112 dollars om måneden.

SimpleMDE (browser)

Selv om du teknisk set kan skrive markdown i enhver teksteditor, fordi det er en måde at formatere almindelig tekst på og ikke strengt taget et “værktøj”, vil det ikke overraske dig, at det også er muligt i din browser! SimpleMDE er både en funktionel markdown-editor bygget på JavaScript og et open source-projekt, som du kan lære af og tilpasse til dit eget brug, hvis det er nødvendigt.

SimpleMDE er 100 % gratis! Få kilden på GitHub her.

reStructuredText-editorer

Markdown er et af de to mest anvendte sprog til at skrive softwaredokumentation, men der er et andet sprog, som vi ikke har kigget på indtil videre, og det er reStructuredText. Det minder meget om markdown, men er værd at lære til softwaredokumentationsformål.

Docutils, skaberen af reStructuredText, har sammensat en liste over reStructuredText-editorer her, som bl.a. omfatter:

Pointen med reStructuredText er, at det er nemt at konvertere mellem forskellige formater, især fra almindelig tekst til et statisk websted. Se mere info her.

Værktøjer til automatisk at generere dokumentation fra kildekode

Der er intet som det menneskelige præg, når det kommer til dokumentation (det er tydeligt i dokumentationen for Slack og Giphy, for at nævne et par stykker). Som udgangspunkt (især for store kildebiblioteker) er det dog bedst at generere skeletdokumentationen automatisk. Dette arbejde ved at analysere kildens funktioner og kommentarer, og der er et par forskellige muligheder afhængigt af sprog:

Hvor du går i gang og udelukkende stoler på automatisk generering, vil jeg foreslå at du læser denne StackExchange-tråd, som vejer fordele og ulemper.

Slutord om softwaredokumentation

Der findes masser af smarte løsninger, hurtige løsninger og værktøjer, der (helt ærligt) er næsten identiske. Det, der betyder noget i sidste ende, er, at

Det, der betyder mest, i sidste ende, er, at:

a) du skriver softwaredokumentation for hvert stykke software, du bygger
b) du skriver den omfattende og hoster den et sted, som brugeren kan få adgang til

Jeg nævnte tidligere, at jeg havde et par flere udviklingsproces-skabeloner, som du måske gerne vil tjekke ud?

Jamen, her er de…

Process Street udviklingsproces-skabeloner

Hvor jeg giver dig disse skabeloner, vil jeg gerne forklare dig lidt mere om, hvad Process Street er.

Så vi ved, at Process Street er superkraftfulde tjeklister. Det er et stykke software, der hjælper dig med at oprette og administrere processer.

Men vent, der er mere i Process Street end det!

Se denne introvideo for at finde ud af, hvad jeg mener:

Så du kan se, at du ikke kun kan oprette en skabelon for en udviklingsproces og køre individuelle tjeklister ud fra denne, hver gang du skal gennemføre udviklingsprocessen, men du kan også tilpasse den ved hjælp af disse ekstra funktioner

• Stop opgaver
• Dynamiske forfaldsdatoer
• Opgavetilladelser
• Konditionel logik
• Godkendelsesopgaver
• Embed widget
• Rolletildelinger

Tildel opgaver, få godkendelse, håndhæve en rækkefølge, som opgaverne skal udføres i, og du kan forbinde processen med tusindvis af apps via Zapier, webhooks eller API-integration.

Se dette webinar om vores nyeste funktioner, og se, hvordan du kan få mest muligt ud af dem:

Med alt dette i baghovedet kan du tage et kig på nedenstående forudlavede skabeloner:

Tjekliste for netværkssikkerhedsrevision

Denne skabelon kan bruges af en risikomanager eller tilsvarende it-professionel til at vurdere et netværk for sikkerhedssårbarheder.

Klik her for at få adgang til tjeklisten for netværkssikkerhedsrevision!

Tjekliste for månedlig vedligeholdelse af websted

Brug denne tjekliste for månedlig vedligeholdelse af websted til at optimere webstedets indlæsningshastighed, scanne for sårbarheder og gennemgå din synlighed i søgemaskiner.

Klik her for at få adgang til tjeklisten for månedlig vedligeholdelse af websted!

Tutorial til softwaretestning

Denne proces kan bruges til at styre et helt softwareudviklingsprojekt fra start til slut, herunder design, håndtering af kunder og også kontrol efter lanceringen.

Klik her for at få adgang til Software Testing Tutorial!

Og der har du det.

Du er nu fri til at bruge det, der gør dit liv nemmere. Jeg håber, at du finder dit nye yndlingsværktøj på denne liste.