Afbeelding door redacteur
 

Dus je voltooide je project, kreeg een aantal uitstekende gegevens, verwerkte het, maakte het schoon, trainde je model, paste het toe op je gegevens en behaalde geweldige resultaten. Dat is het.

Niet echt.

Vaak is de software ontwikkeld voor gebruik door anderen, dus zodra de programmeur of datawetenschapper klaar is met het bouwen van het project, moeten ze de taak uitvoeren die de meesten van ons haten...

Documenteren van de code.

In software-engineering verwijst het schrijven van documentatie in het algemeen naar het proces waarbij de programmeur van de hoofdontwikkelaar van de code een script schrijft waarin in detail wordt uitgelegd wat de code doet, het doel ervan en hoe het dat bereikt. De belangrijkste reden waarom programmeurs een hekel hebben aan het schrijven van documentatie, is dat je als programmeur liever code schrijft dan een uitleg ervan.

Niet alleen dat, wil documentatie goed zijn, dan moet het voor iedereen eenvoudig te begrijpen zijn, zelfs als het geen professionele programmeur is. En zoals we allemaal weten - misschien niet allemaal - zijn programmeurs goed in het schrijven van code, maar slecht in het uitleggen van de theorie ervan.

Aan het begin van uw documentatie moet een korte, beknopte beschrijving staan. Deze beschrijving mag slechts een paar zinnen lang zijn en moet duidelijk uitleggen wat het project doet en hoe het het doet.

Je hebt al enkele open-sourceprojecten gebruikt in je vorige werk, dus hier zijn enkele uitstekende beschrijvingen van bekende data science-projecten.

Pandas: “Panda's is een snelle, krachtige, flexibele en gebruiksvriendelijke open source tool voor gegevensanalyse en -manipulatie, gebouwd bovenop de Python programmeertaal." - Panda's documentatie

matplotlib: “Matplotlib is een uitgebreide bibliotheek voor het maken van statische, geanimeerde en interactieve visualisaties in Python. Matplotlib maakt gemakkelijke dingen makkelijk en moeilijke dingen mogelijk.” — Matplotlib-documentatie

Bokeh: “Bokeh is een interactieve visualisatiebibliotheek voor moderne webbrowsers. Het biedt een elegante, beknopte constructie van veelzijdige grafische afbeeldingen en biedt hoogwaardige interactiviteit over grote of streaming datasets. Bokeh kan iedereen helpen die snel en eenvoudig interactieve plots, dashboards en data-applicaties wil maken.” - Bokeh-documentatie.

Wanneer u een project ontwikkelt, host u het vaak op een externe server zodat mensen het kunnen gebruiken. Ze zullen het waarschijnlijk moeten klonen van GitHub, installeren met pip of downloaden van de officiële website.

Dit lijkt misschien eenvoudig voor ervaren programmeurs; ze hebben tijdens hun carrière immers veel bibliotheken geïnstalleerd. Maar wat als een nieuwe programmeur uw project probeert te gebruiken? Ze hebben misschien een beetje hulp nodig.

Na het beschrijven van uw project en wat het doet, zou het volgende een sectie "Aan de slag" moeten zijn. Het primaire doel van die sectie is om de gebruiker eenvoudige stappen te geven om het project te installeren en een klein voorbeeld uit te voeren om te bewijzen dat het correct is geïnstalleerd.

Bovendien bevat het vaak de afhankelijkheden — andere bibliotheken of modules — waarvan dit project afhankelijk is om goed te kunnen functioneren.

Op dit punt weet de gebruiker wat het project doet en hoe het te installeren. Nu is het tijd om diep te graven en het te gaan gebruiken. Goede documentatie bevat vaak tutorials over de verschillende gebruiksscenario's van het project en hoe dit voor elkaar te krijgen met behulp van de interne functies van het project.

Veel tutorials staan ​​niet gelijk aan goede documentatie; het gaat niet om kwantiteit maar om kwaliteit. Sommige projecten hebben echter een paar tutorials die het gebruik van het project benadrukken, waarbij duidelijk wordt aangegeven hoe het kan worden uitgebreid om op andere gevallen van toepassing te zijn. Dit betekent dat de gebruiker slechts 2 of 3 tutorials hoeft te lezen om de interne werking van de projectcode te begrijpen.

De meest gebruikte tutorial-indeling is om een ​​paar regels uitleg te hebben, gevolgd door wat code, meer beschrijving, enz.

Dit deel komt meestal in je op als je het woord documentatie hoort - of leest. In dit gedeelte doorloopt u alle functies, openbare variabelen en klassen binnen uw project, waarbij u de functionaliteit, attributen en rendementen kort uitlegt.

De korte uitleg bestaat vaak uit twee of drie zinnen en legt direct het doel van de functie/klasse uit, waarbij het type, de algemene typen attributen en de terugkeer in de vorm van een functiekop worden weergegeven. Deze header bevat vaak een ingesloten link naar de functie-/klassedefinitie van de broncode (waar deze ook wordt gehost).

Tot nu toe heeft uw documentatie uitgelegd hoe de kern van uw project werkt, de belangrijkste functies en enkele gebruiksscenario's. In het laatste deel van de documentatie moet worden uitgelegd waarom uw project werkt zoals het werkt.

Niet alle code bevat deze sectie; het is tenslotte niet zo essentieel als de andere secties die we hebben doorgenomen. Deze sectie kan echter nodig zijn om uw project open source te maken. In dit geval kan deze sectie de bijdragers helpen hoe ze nieuwe functies aan de code kunnen toevoegen zonder de kernfunctionaliteit aan te tasten.

Tegenwoordig is er meer nodig dan het schrijven van robuuste code; om uw capaciteiten te bewijzen en hoe goed u bekend bent met het project en het veld, moet u goedgeschreven documentatie verstrekken en benadrukken hoe uw code werkt en hoe deze kan worden gebruikt.

Het maken van goede documentatie is van veel factoren afhankelijk; in dit artikel hebben we 5 secties doorgenomen die, indien opgenomen, waarde toevoegen aan uw documentatie en deze zo nuttig mogelijk maken.

U moet denken dat de term "goede documentatie" erg vaag is en van de persoon afhangt. Ik kan bijvoorbeeld sommige documentatie als goed en nuttig beschouwen, terwijl u misschien het tegenovergestelde denkt. Als we geen rigide regels kunnen stellen aan wat goede documentatie is, hoe kunnen we bepalen of de documentatie goed is?

Het simpele antwoord daarop is feedback. De meeste moderne documentatie bevat vaak een "geef ons feedback" sectie. Gebruikers kunnen contact opnemen met de programmeur over ontbrekende of onnauwkeurige informatie in de documentatie om deze beter en nuttiger te maken.
 
 
Sara Metwalli is een Ph.D. kandidaat aan de Keio University onderzoekt manieren om kwantumcircuits te testen en te debuggen. Ik ben een IBM-onderzoeksstagiair en voorstander van Qiskit om te helpen bouwen aan een meer kwantumtoekomst. Ik ben ook een schrijver over Medium, Built-in, She Can Code en KDN en schrijf artikelen over programmeren, datawetenschap en technische onderwerpen. Ik ben ook een leider in het internationale hoofdstuk Woman Who Code Python, een treinliefhebber, een reiziger en een liefhebber van fotografie.
 

• Door SEO aangedreven content en PR-distributie. Word vandaag nog versterkt.
• Platoblockchain. Web3 Metaverse Intelligentie. Kennis versterkt. Toegang hier.
• Bron: https://www.kdnuggets.com/2022/12/5-rules-good-data-science-project-documentation.html?utm_source=rss&utm_medium=rss&utm_campaign=the-5-rules-for-good-data-science-project-documentation