18 Software Documentation Tools that Do The Hard Work For You

🟢 Bonusmateriaal: Git Workflow Checklist om & versiebeheer te vereenvoudigen

Zonder documentatie is software niet meer dan een zwarte doos. En zwarte dozen zijn lang niet zo nuttig als ze zouden kunnen zijn, omdat hun innerlijke werking verborgen is voor degenen die ze in de openbaarheid nodig hebben.

Softwaredocumentatie verandert uw software in een glazen doos door aan gebruikers en ontwikkelaars uit te leggen hoe het werkt of wordt gebruikt.

Je hebt waarschijnlijk al eerder documentatie gezien, maar als je een opfrisser nodig hebt, is hier een voorbeeld van de API van Slack:

Zoals je kunt zien, legt Slack alles over zijn API in ondraaglijk detail uit. Alle gerelateerde pagina’s zijn gelinkt, er is een zijbalk met gemakkelijk toegankelijke onderwerpen, en screenshots van wat de gebruiker kan verwachten te zien.

Om dit in meer detail uit te leggen, zullen we de volgende onderwerpen in deze Process Street post behandelen:

• Wat is softwaredocumentatie?
• Hostingopties voor softwaredocumentatie
• Schrijftools voor softwaredocumentatie
• Eindwoorden over softwaredocumentatie

Laten we aan de slag gaan.

Wat is softwaredocumentatie?

“Documentatie in software engineering is de overkoepelende term die alle geschreven documenten en materialen omvat die te maken hebben met de ontwikkeling en het gebruik van een softwareproduct” – Prototype.io, Software Documentation Types and Best Practices

Alle software zou een vorm van documentatie moeten hebben die in detail uitlegt wat het product is, hoe het werkt en waarom het op die manier werkt.

“Als het niet gedocumenteerd is, bestaat het niet” – Sitepoint, A Guide to Writing Your First Software Documentation

Als ontwikkelaar is het je belangrijkste doel om de beste code te schrijven die je maar kunt bedenken. Je wilt dat je code de beste in zijn klasse is, gemakkelijk te lezen, gemakkelijk te gebruiken, en je wilt dat er geweldige dingen gebeuren als gevolg van die code. Toch?

Maar zonder te documenteren wat je hebt gedaan en waarom je het hebt gedaan:

• Niemand anders kan je code gebruiken dan jij

Zonder documentatie zal niemand begrijpen wat je hebt gedaan en waarom je het hebt gedaan. Het zal ongelooflijk moeilijk zijn, bijna onmogelijk, voor iemand anders om je code op te pakken en eraan te werken. Ze zouden het zelfs kunnen schrappen en opnieuw beginnen, omdat dat in sommige gevallen sneller zou zijn dan proberen uit te zoeken wat je hebt gedaan en waarom.

• Je kunt het niet bijwerken of verbeteren

Kunt u zich herinneren wat u zaterdag drie maanden geleden als avondeten hebt gegeten? Tenzij je een gewoontedier bent, is de kans groot van niet. Dus het is waarschijnlijk dat u zich de code die u schreef twee, drie, vier maanden nadat u die schreef, niet meer herinnert. Als je je de redenen achter je coderingsbeslissingen niet kunt herinneren, dan zul je moeite hebben om het te kunnen bijwerken of verbeteren.

Desondanks is softwaredocumentatie vaak een taak die wordt gehaast, slecht wordt gedaan, geen prioriteit krijgt, of helemaal wordt vergeten.

Voordat we gaan praten over welke tools je kunt gebruiken om softwaredocumentatie te schrijven, moeten we een manier bedenken om ervoor te zorgen dat de taak in de eerste plaats wordt gedaan.

Dit is waar Process Street kan helpen.

Process Street is een stuk van business process management (BPM) software die kan worden gebruikt om processen te creëren, beheren en volgen.

Meer over wat Process Street is later, voor nu, laat me je zien hoe je het kunt gebruiken als een hulpmiddel om je te helpen software documentatie in te passen in elk software-ontwikkelingsproject waar je aan werkt.

Hieronder staat een voorbeeld van een kant-en-klare Software Deployment Process template. Dit sjabloon is gemaakt om software engineers en programmeurs te helpen hun software op de best mogelijke manier te implementeren.

Klik hier om toegang te krijgen tot het Software Deployment Proces!

Om deze sjabloon te krijgen, logt u in en voegt u het toe aan uw dashboard, of meldt u zich aan voor een gratis proefperiode.

Dit sjabloon is een perfect voorbeeld van een proces dat u kunt volgen elke keer dat u een nieuw of bijgewerkt stuk code wilt implementeren.

Het heeft duidelijke stappen die u door het hele implementatieproces leiden, van het opzetten van een staging omgeving tot het live zetten van uw wijzigingen. Deze stappen zorgen ervoor dat niets wordt gemist en dat het hele proces soepel verloopt, elke keer weer.

We hebben dit sjabloon ontworpen om te gebruiken als een gids om u te helpen een implementatieproces te creëren dat voor u werkt. Elk bedrijf is anders, elk softwareproject is anders, en elk implementatieproces is anders.

U kunt dit proces bewerken en de taken toevoegen die voor u, uw bedrijf en uw project van belang zijn.

Dat brengt me terug bij de softwaredocumentatie; je zou ‘softwaredocumentatie’ als taak kunnen toevoegen. Op die manier zal iedereen die werkt door middel van de software implementatie proces worden herinnerd en aangemoedigd om dit te voltooien, als onderdeel van het proces.

Ik heb nog een paar kant-en-klare processjablonen die je misschien van pas kunnen komen, die ik aan het eind van dit bericht zal opnemen.

Voordat we daar aan beginnen, laten we eens kijken waar je je softwaredocumentatie kunt opslaan.

Hostingopties voor softwaredocumentatie

Het is niet goed om alleen maar een stel tekstbestanden op je computer te hebben staan. Ze moeten toegankelijk zijn voor ontwikkelaars en gebruikers, die je waarschijnlijk gaat doen door het hosten van de docs op het internet, omdat het niet de jaren 1980.

Process Street (voor intern gebruik)

Voor het trainen van nieuwe ontwikkelaars en het houden van uw documentatie leven allemaal op dezelfde plaats, Process Street is een solide keuze voor softwaredocumentatie.

Eerst zou u een proces kunnen creëren voor het schrijven van uw documentatie, om ervoor te zorgen dat u alle juiste details vastlegt en het zo nuttig mogelijk maakt.

Met behulp van de volgende eenvoudig te gebruiken functies kunt u vervolgens uw documentatie op één enkele plaats schrijven en opslaan:

• Image widgets
• Tekst widgets
• Video widgets
• Bestand widgets
• Subtaken
• Email widgets
• Embed widgets

Het opslaan van uw documentatie binnen Process Street betekent dat deze door iedereen in het bedrijf kan worden geraadpleegd. U kunt het met anderen delen, ter goedkeuring verzenden, herinneringen instellen om het te herzien en het eenvoudig bijwerken.

Kijk maar eens:

Als het kan worden gedocumenteerd, kan het worden gedocumenteerd in Process Street.

Teken hier in voor een gratis proefversie en probeer het eens.

Read The Docs

Het is opmerkelijk dat Read The Docs gratis is als je ziet wat het allemaal kan doen. Net als bij GitHub kun je zoveel open-source materiaal maken als je wilt dat openlijk geïndexeerd wordt op de site, maar het gaat je geld kosten als je de documenten privé en intern wilt maken voor je bedrijf. Voor onze doeleinden is het waarschijnlijk goed dat de documenten direct beschikbaar zijn voor gebruikers op het web.

De reden waarom Read The Docs zo goed is, is dat u moeiteloos documentatie kunt importeren uit elk versiebeheersysteem, waaronder Git, Mercurial, Subversion en Bazaar. Het ondersteunt ook webhooks, zodat de docs automatisch worden gebouwd wanneer je code commit.

Check hun Getting Started gids om een gevoel te krijgen hoe het werkt en hoe je docs zich zouden gedragen wanneer ze daar gehost worden.

GitHub (& GitHub Pages)

Als je GitHub gebruikt om versiebeheer voor je software te beheren, heb je, op zijn minst, een README.MD bestand in de repository. Om GitHub te gebruiken voor het documenteren van je software, zoals miljoenen anderen in het verleden hebben gedaan, vul je die README gewoon in met markdown.

Een goed voorbeeld is sferik’s t repository, hier te zien:

Als je meer wilt dan alleen een vel geformatteerde tekst, dan kun je gebruik maken van GitHub’s Pages tool (je krijgt een gratis webpagina + hosting bij elke GitHub account, en je kunt er zelfs een eigen domein aan koppelen). Pages heeft zelfs geweldig uitziende standaardthema’s die je documentatie er professioneel uit laten zien.

Hierboven zie je de documentatie van atom.io voor Electron, gehost op GitHub. Het is een slimme keuze omdat het automatisch werkt met GitHub’s versiebeheer, net als de rest van je software. Bekijk de repository van de site hier.

Dropbox Paper (voor intern gebruik)

Voor intern softwaredocumentatiegebruik is Dropbox Paper een uitstekende keuze. Net als zijn voorganger Hackpad, kunt u het gebruiken om een eigen wiki voor medewerkers te maken. Je kunt documenten aan elkaar koppelen, codeblokken, afbeeldingen en paginasprongetjes invoegen, net zoals je van elk documentatiehulpmiddel zou eisen.

Zoals je in de opmerkingen hiernaast kunt zien, kun je het ook gebruiken om goedkeuringsprocessen te doorlopen en samen te werken aan de totstandkoming van documentatie. Over het geheel genomen is het een geweldig hulpmiddel voor het intern ontwikkelen en maken van documentatie, misschien met de bedoeling deze later te publiceren, of gewoon voor intern gebruik te bewaren.

Atlassian REST API Browser (voor API-gebruik)

Atlassian’s REST API Browser (RAB) wordt standaard meegeleverd met JIRA Server, Confluence Server en Stash instances. Het is gebouwd voor het ontdekken van API’s die beschikbaar zijn voor gebruik in JIRA/Confluence-omgevingen, en ook een plaats om uw documentatie te hosten. Als uw API in het plaatje past, natuurlijk.

Documenteer uw API met deze tool om uw API die compatibel is met JIRA/Confluence meer bekendheid te geven. Kijk hier voor de documentatie van Atlassian over hoe je dat doet.

Tettra (voor intern gebruik)

Tettra is een soort kennisbank-software waarin je je ontwikkeling, of wat dan ook, kunt documenteren.

We gebruiken Tettra intern bij Process Street voor een heleboel use-cases. Van dag tot dag gebruik ik Tettra om een plek te hebben waar al mijn processen zijn gedocumenteerd, zodat ik nooit vergeet hoe de een zich verhoudt tot de ander of hoe de verschillende automatiseringen die we hebben gebouwd zijn opgezet.

Tettra is geweldig als je op zoek bent om een soort bibliotheek te maken. Dit betekent dat het is briljant voor software documentatie of zelfs gewoon als een interne wiki voor uw bedrijf.

Gezien het feit dat Tettra is speciaal ontworpen voor kennismanagement, het wordt geleverd met een groot aantal andere ondersteunende functies ook. Zo kan het suggesties doen over welke extra inhoud of secties u zou willen toevoegen om een completer beeld te geven van uw org en hoe dingen bij elkaar passen.

U kunt hier een kleine video zien voor hoe een dev team eruit zou kunnen zien om Tettra te gebruiken: How Product & Engineering Teams Use Tettra.

Of, je kunt hier gaan om te lezen over hoe we Tettra gebruiken naast Process Street: Het automatiseren van workflows en checklists: Process Street Case Study.

Check it out!

Apiary (voor API gebruik)

Naast een plek waar bijen leven, is Apiary een speciale host voor API documentatie. Schrijf in markdown, voeg mock API-calls toe en Apiary voegt dat samen tot iets zoals je hieronder ziet:

Iedereen kan de API testen zonder in de app te hoeven gaan of daadwerkelijk een call te programmeren, wat het een super toegankelijke manier maakt om je API te delen, diepgaand te documenteren, en op te scheppen over wat het kan doen.

We hebben besproken waar u uw softwaredocumentatie opslaat, nu is het tijd om te kijken hoe u deze schrijft.

Hulpmiddelen voor het schrijven van softwaredocumentatie

Softwaredocumentatie wordt vaak geschreven in markdown om hyperlinks en opmaak mogelijk te maken, terwijl het toch platte tekst blijft, zodat het naast de codebestanden in versiebeheer kan worden gebruikt. Dat betekent dat veel van mijn keuzes voor schrijfgereedschappen eenvoudige markdown-editors zijn die de schrijfervaring plezierig maken. Daarnaast zijn er ook een paar zeer effectieve niet-markdown oplossingen bijgekomen.

MarkdownPad (Windows)

Met een gratis en premium versie – beide met een ton aan geweldige functies – is MarkdownPad de meest populaire markdown editor voor Windows. Het is geoptimaliseerd voor blogposts, websites, artikelen, README’s en natuurlijk softwaredocumentatie.

Je kunt MarkdownPad gratis krijgen, of de premium versie voor $14,95.

iA Writer (Mac)

iA Writer is een eenvoudige, mooie markdown-editor met een bibliotheekfunctie waarmee je eenvoudig terug kunt verwijzen naar andere documenten in de zijbalk. Het mist interne links tussen documenten zoals je zou verwachten dat er in software docs, maar je kunt altijd doen een pass op die wanneer het in zijn definitieve vorm (dat wil zeggen, als het gaat om te eindigen op het internet in een site).

Als u schrijft uw hele documentatie in een, opgesplitst pagina, kunt u gebruik maken van pagina springen ankers om gebruikers te helpen navigeren.

iA Writer kost $ 9,99 in de Mac App Store.

Profs Knowledge Base

Profs Knowledge Base is een fantastisch klein hulpprogramma voor alle fasen van het maken van documenten; van schrijven en bewerken, tot aanpassen, het instellen van workflows en publiceren. U kunt multimedia toevoegen, bestaande inhoud importeren uit Word-docs, PDF’s of PPT’s, meerdere versies van het document opslaan en deze indien nodig weer herstellen.

Maar de echte schoonheid van deze tool ligt in zijn bruikbaarheid. Iedereen kan het gebruiken om softwaredocumentatie te maken. Of je nu al jaren software documenteert of pas sinds kort, het is een ongelooflijk eenvoudige en makkelijk te gebruiken tool.

Profs is gratis te gebruiken, of je kunt upgraden naar het premium pakket dat $112 per maand kost.

SimpleMDE (browser)

Hoewel je technisch gezien in elke teksteditor markdown kunt schrijven, omdat het een manier is om platte tekst op te maken en niet strikt een ’tool’, zal het je niet verbazen dat het ook in je browser mogelijk is! SimpleMDE is zowel een functionele markdown-editor gebouwd op JavaScript als een open-source project om van te leren en aan te passen voor je eigen gebruik, indien nodig.

SimpleMDE is 100% gratis! Haal de broncode hier op GitHub.

reStructuredText editors

Markdown is een van de twee meest gebruikte talen voor het schrijven van softwaredocumentatie, maar er is er nog een waar we tot nu toe niet naar hebben gekeken, en dat is reStructuredText. Het lijkt erg op markdown, maar het is de moeite waard om te leren voor software documentatie doeleinden.

Docutils, de maker van reStructuredText, heeft hier een lijst van reStructuredText editors samengesteld, met onder andere:

Het punt van reStructuredText is dat het eenvoudig is om te converteren tussen verschillende formaten, vooral van platte tekst naar een statische website. Zie meer info hier.

Tools om automatisch documentatie te genereren uit broncode

Er gaat niets boven de menselijke maat als het gaat om documentatie (het is duidelijk te zien in de docs van Slack en Giphy, om er een paar te noemen). Maar om te beginnen (vooral voor grote bronbibliotheken), kun je het beste de skeletdocumentatie automatisch genereren. Dit werkt door de functies en commentaren van de broncode te analyseren, en er zijn een paar verschillende opties, afhankelijk van de taal:

Voordat u uitsluitend vertrouwt op automatische generatie, raad ik u aan deze StackExchange-draad te lezen waarin de voor- en nadelen tegen elkaar worden afgewogen.

Eindwoorden over softwaredocumentatie

Er zijn tal van mooie oplossingen, snelle oplossingen en tools die (eerlijk gezegd) bijna identiek zijn. Waar het uiteindelijk om gaat is dat

Wat er uiteindelijk het meest toe doet, is dat:

a) je softwaredocumentatie schrijft voor elk stuk software dat je bouwt
b) je die uitgebreid schrijft en ergens host waar de gebruiker erbij kan

Ik zei eerder dat ik nog een paar ontwikkelprocessjablonen had die je misschien graag zou willen bekijken?

Wel, hier zijn ze…

Process Street ontwikkel process templates

Voordat ik je deze templates geef, laat me je eerst wat meer uitleggen wat Process Street is.

Dus we weten dat Process Street super-powered checklists zijn. Het is een stuk software dat u zal helpen processen te creëren en te beheren.

Maar wacht, er is meer aan Process Street dan dat!

Bekijk deze intro video om uit te vinden wat ik bedoel:

Zo zie je maar, je kunt niet alleen een ontwikkel proces sjabloon maken en individuele checklists uitvoeren van dit elke keer dat je het ontwikkel proces moet voltooien, maar u kunt het ook aanpassen met deze extra functies

• Stop taken
• Dynamische vervaldata
• Taak permissies
• Conditional logic
• Approval taken
• Embed widget
• Rol toewijzingen

Toekennen taken, krijg goedkeuring, dwing een volgorde af waarin de taken worden voltooid, en u kunt het proces koppelen aan duizenden apps via Zapier, webhooks of API-integratie.

Bekijk dit webinar over onze nieuwste functies en zie hoe u er het meeste uit kunt halen:

Met dit alles in gedachten, neem een kijkje naar de onderstaande vooraf gemaakte sjablonen:

Network Security Audit Checklist

Deze sjabloon kan worden gebruikt door een risicomanager of gelijkwaardige IT-professional om een netwerk te beoordelen op kwetsbaarheden in de beveiliging.

Klik hier om toegang te krijgen tot de Network Security Audit Checklist!

Maandelijkse Website Onderhoud Checklist

Gebruik deze maandelijkse website onderhoud checklist om de laadsnelheid van uw site te optimaliseren, te scannen op kwetsbaarheden, en uw zoek zichtbaarheid te beoordelen.

Klik hier om toegang te krijgen tot de Maandelijkse Website Onderhoud Checklist!

Software Testen Tutorial

Dit proces kan worden gebruikt om een gehele software ontwikkelingsproject van begin tot eind te beheren, inclusief ontwerp, afhandeling door de klant, en ook post-launch controles.

Klik hier om naar de Software Testing Tutorial te gaan!

En daar heb je het.

Je bent nu vrij om te gebruiken wat je leven makkelijker maakt. Ik hoop dat u in deze lijst uw nieuwe favoriete hulpmiddel vindt.