Inleiding

Stel je voor dat je een open-source project hebt ontdekt dat perfect aansluit bij je interesses. Je staat te popelen om het te gebruiken of eraan bij te dragen, maar waar begin je? Het antwoord ligt in de documentatie van het projectdocumentatie.

Denk nu aan Open Source Documentatie als een gids om een gebruiker te helpen het meeste uit een project te halen. Het leidt de gebruiker door de complexiteiten van het project, terwijl het hen ook helpt de kernprincipes van het project te begrijpen, hoe het te gebruiken en hoe ze bijdragen kunnen leveren.

In dit artikel zullen we kijken naar Open Source documentatie, de soorten open source documentatie bespreken, het belang ervan bespreken, best practices voor het maken ervan en tot slot tools om het proces van het maken van open source documentatie te stroomlijnen.

Wat is Open Source Documentatie precies?

Om te beginnen, laten we “Open source” definiëren. Open Source in eenvoudige bewoordingen betekent een type software waarvan de broncode vrij beschikbaar is voor het publiek om te inspecteren, aan te passen, te verbeteren en te verspreiden. Bijvoorbeeld: het Linux-besturingssysteem, de Firefox-webbrowser, MongoDB, enz.

Nu verwijst Open Source Documentatie naar geschreven materialen die geassocieerd worden met Open Source software. Het biedt informatie over het gebruik, de functionaliteit en het onderhoud van de producten. Het bevat details en informatie over de functies van de software, installatieconfiguratie en gebruik. Deze documentatie is meestal beschikbaar voor het publiek naast de broncode.

Open Source-documentatie fungeert als een uitgebreide bron voor ontwikkelaars, gebruikers en bijdragers, en biedt essentiële informatie over het doel, de functies en het gebruik van het project. In eerste instantie kunnen Open Source-projecten overweldigend aanvoelen, maar met behulp van goede documentatie kunnen gebruikers en bijdragers het project begrijpen.

Soorten Open-Source Documentatie

Open Source-projecten hebben meestal 3 soorten documentatie. Elk ervan voldoet aan specifieke behoeften. Ze omvatten Technische Documentatie, Product Documentatie en Richtlijnen.

Technische Documentatie: Deze documentatie is voor ontwikkelaars. Het duikt diep in de codebasis, legt de API uit en toont hoe de programmeerinterface van het project wordt gebruikt. Het bevat ook inleidende documenten voor het project, richtlijnen voor ontwikkelaars die met het project werken, en instructies voor het configureren van de ontwikkelomgeving. API-documentatie, ontwikkelingshandleidingen en README zijn goede voorbeelden van technische documentatie.

Product Documentatie: Deze documentatie is gericht op de gebruikers van het project. Ze omvatten gebruikershandleidingen, snelstartgidsen, installatiegidsen, probleemoplossingsgidsen, FAQ’s, enz. Ze richten zich voornamelijk op de gebruikerservaring en begeleiden de gebruikers bij het begrijpen van de projecten, de functies en hoe het project te gebruiken.

Richtlijnen: Deze documentatie is afgestemd op de bijdragers aan het project. Ze helpen bijdragers begrijpen hoe ze door het project kunnen navigeren. De gebruikelijke soorten richtlijnen voor Open Source-projecten zijn:

Contribution guides : Ze zijn echt belangrijk omdat ze uitleggen hoe bij te dragen aan het project, inclusief code-indieningen en bugrapporten/ fixes.
Style guides: bieden informatie over de voorkeursstijl, opmaak en benoemingsconventies. Het zorgt voor kwaliteit en consistentie in de code en bijdragen.
Code of Conduct : geeft het verwachte gedrag van bijdragers en gemeenschapsleden weer.

Belang van Open Source-documentatie

Goede documentatie is van het grootste belang voor zowel de gebruiker van het project als de bijdrager aan het project. Laten we eens kijken hoe goede documentatie de gebruikers en bijdragers aan een Open Source-project helpt.

Voor Gebruikers:

Verbeterde Gebruikerservaring : Goede documentatie helpt de gebruiker te begrijpen hoe het project effectief te gebruiken en er het meeste uit te halen. Het biedt een snellere oplossing voor problemen waar een gebruiker tegenaan kan lopen bij het gebruik van het project.
Eenvoudigere adoptie en gebruik van de software: Duidelijke en beknopte documentatie maakt het gemakkelijker om de functies en functionaliteit van de software te begrijpen. Het verkort de leercurve en maakt de software toegankelijker voor een breder scala aan gebruikers.
Probleemoplossing: Gedetailleerde documentatie kan gebruikers helpen bij het oplossen van problemen en het onafhankelijk vinden van oplossingen. Dit vermindert de afhankelijkheid van ondersteunend personeel en verbetert de algehele gebruikerservaring.
Verlaagde ondersteuningskosten: Goede documentatie kan helpen het aantal ondersteuningsvragen te minimaliseren, wat tijd en middelen bespaart voor zowel gebruikers als ontwikkelaars.

Voor Bijdragers:

Duidelijker begrip van het project : Om bij te kunnen dragen aan een project, is het nodig om het project te begrijpen. Goede documentatie helpt de lezer het project te begrijpen en hoe ze kunnen beginnen met hun bijdrage.
Effectieve Onboarding : Goede documentatie vergemakkelijkt een soepel onboardingsproces voor de bijdragers. Het helpt hen meer vertrouwd te raken met de codebase van het project, de workflow en de noodzakelijke details die ze nodig hebben om hun bijdragen te leveren.
Verbeterde Samenwerking: Duidelijke en beknopte documentatie creëert een gemeenschappelijke basis voor bijdragers, zodat iedereen de doelen, architectuur en coderingsnormen van het project begrijpt. Bijdragers kunnen gemakkelijk de informatie krijgen die ze nodig hebben om hun taken uit te voeren, waardoor vertragingen en misverstanden worden verminderd.

Beste praktijken om goede documentatie te bereiken

Uit wat we tot nu toe hebben besproken, blijkt dat het schrijven van goede documentatie voor uw open source project echt cruciaal is. Om goede documentatie te kunnen realiseren die voldoet aan de behoeften van uw gebruikers en bijdragers aan het project, zijn hier een paar dingen die u kunt doen.

Schrijf op een duidelijke en beknopte manier om uw lezers gemakkelijk te laten begrijpen wat u daar plaatst. Het is belangrijk om het gebruik van complexe technische jargon te vermijden die uw lezers zouden kunnen verwarren, aangezien het doel van de documentatie is om de gebruikerservaring te verbeteren

Organiseer uw documentatie op een gestructureerde manier en patroon. Om dit te bereiken, moet u uw informatie logisch rangschikken met behulp van koppen, subkoppen en opsommingstekens. Uw documentatie moet een gestructureerd patroon volgen, alles moet goed van boven naar beneden stromen en het moet gemakkelijk zijn voor lezers om te volgen
Schrijf met de behoeften van de gebruiker in gedachten. Het is belangrijk om je in hun schoenen te plaatsen, jouw documentatie moet een nuttige hulpbron zijn, geen drempel om binnen te komen. Leg concepten zo duidelijk mogelijk uit; ga er niet vanuit. Je kunt codefragmenten toevoegen om specifieke concepten uit te leggen, veelvoorkomende vragen te anticiperen en eenvoudige oplossingen/antwoorden te bieden.
Houd je documentatie up-to-date door deze bij te werken wanneer er wijzigingen worden aangebracht in het project. Je documentatie moet samen met de code worden verzonden, naarmate de codebasis wordt bijgewerkt, moet ook de documentatie worden bijgewerkt.
Bied duidelijke instructies over hoe bij te dragen aan het project. Op deze manier kunnen mensen die bereid zijn bij te dragen hun weg vinden in het project en tegelijkertijd gemakkelijk wijzigingen aanbrengen.
Controleer op fouten, inconsistenties of verouderde informatie. Vraag ook om feedback van je gebruiker, dit helpt de documentatie te verbeteren.
Als laatste is het belangrijk om gebruik te maken van tools die kunnen helpen bij het creëren van goede documentatie. Er zijn veel tools beschikbaar die je kunt gebruiken om

Tools om te gebruiken bij het maken van goede documentatie

Zoals eerder gezegd, zijn er veel tools die je kunt benutten om goede documentatie te creëren die gebruikers gemakkelijk kunnen raadplegen en begrijpen. Hier zijn er een paar.

Sphinx : een populair instrument voor het maken van technische documentatie, vooral voor Python-projecten. Het ondersteunt verschillende uitvoerformaten (HTML, PDF, LaTeX) en heeft een rijke ecosysteem van extensies.
Doxygen : een tool voor het genereren van API-documentatie uit opmerkingen in de broncode. Het ondersteunt verschillende programmeertalen en kan documentatie produceren in HTML, LaTeX en andere formaten.
MkDocs: een eenvoudige, snelle en configureerbare documentatiegenerator die Markdown gebruikt voor het schrijven van inhoud. Het is goed geschikt voor kleinere projecten.
Read the Docs: een hostingplatform voor documentatie gebouwd met Sphinx of MkDocs. Het vereenvoudigt software-documentatie door het bouwen, versiebeheer en hosten van uw documentatie.
Git: Git stelt je in staat om wijzigingen in je documentatie in de loop van de tijd bij te houden. Dit betekent dat je gemakkelijk kunt teruggaan naar eerdere versies indien nodig, en het helpt ook bij het voorkomen van per ongeluk verwijderingen. Het helpt bij continue updates van de documentatie.

Je kunt de documentatie van elk van de tools doornemen om een diepgaand begrip te krijgen van hoe ze werken en hoe je aan de slag kunt met het gebruik ervan.

Conclusie

Om af te sluiten, bepaalt goede documentatie hoe goed een project wordt begrepen en gebruikt. Het is essentieel om een duidelijke en beknopte documentatie te hebben die voldoet aan de behoeften van iedereen die een open source project wil gebruiken.

Uit het artikel blijkt dat door tijd en moeite te investeren in het creëren van grondige, goed gestructureerde en toegankelijke documentatie, verbeter je niet alleen de gebruikerservaring maar zorg je ook voor de duurzaamheid van je project.

De volgende keer dat je een Open Source project tegenkomt dat je aandacht trekt, wees dan niet bang om erin te duiken; de documentatie zal je gids zijn bij het gebruiken of bijdragen aan het project.

Resources

https://opensource.googleblog.com/2018/10/building-great-open-source-documentation.html

https://opensource.com/article/20/3/documentation

https://herothemes.com/blog/best-documentation-tools/