Tutorials of documentatie

[Furion2000]

Goedemorgen,

Bij het leren van een nieuw framework pak ik vaak een tutorial als deze compleet nieuw is of een stackoverflow bij issues waar ik half iets van weet, maar vaak stel ik mijzelf de vraag: "zou ik het niet veel beter begrijpen als ik gewoon de hele documentatie van dit framework of library doorneem?".

Als ik dan toch in de documentatie ga grasduinen vind ik het voor mij gevoel niet snel genoeg en is het mij niet duidelijk, maar daartegenover skim je dan meer door documentatie. Skimmen is misschien wel killing om het te kunnen begrijpen? Over het algemeen vind ik documentatie dus niet echt duidelijk, maar ik kan natuurlijk hier de fout zijn in de manier waarop ik het aanvlieg.

Pragmatisch en al doende leren was tot dit moment genoeg om een acceptabel niveau te halen, maar zelf vind ik het best frustrerend dat ik de exacte mechanics soms niet goed op mijn netvlies heb.

Hoe kijken jullie dus tegen documentatie en hoe maken jullie de stap van kunnen werken met een framework naar de exacte werking begrijpen? In andere woorden, hoe maak jullie jezelf een framework helemaal eigen op het niveau dat je kunt zeggen dat je er 'goed in bent'

[ Voor 6% gewijzigd door Furion2000 op 20-03-2022 11:45 ]

[FunkyPeanut]

Hey Furion,

Ik snap je struggle. Ik ben er zelf ook vaak over aan het nadenken.

Voor mij is documentatie echt een soort naslagwerk. Je kunt er alles in vinden wat er uberhaupt mogelijk is met het nieuwe framework, soms met voorbeelden in de goede context, maar vaak ook niet.

Dan heb je natuurlijk de YouTube tutorials die binnen 10 minuten je eigenlijk bijna niks vertellen over waar je naar zoekt. Wel fijn om even een voorbeeld te zien van hoe het werkt, maar blijft vaak enorm aan de oppervlakte. Maar het kan je een soort kickstart geven.

Voor mij werkt het dus het beste om echt een goede tutorial, of een goed boek / artikel / blogpost erover te vinden en het dan zelf uit te proberen, zodat je voelt hoe het werkt in de context waar jij in werkt. Ik heb een aantal go-to sites en developers, waarvan ik weet dat als ik daar naar een onderwerp zoek, dat ze echt de diepte in gaan, maar dat het altijd vanuit het perspectief van een gebruiker is geschreven.

My 2 cents

[RobIII]

De ene documentatie is de andere niet, de ene tutorial is de andere niet. Dus er is geen eenduidig antwoord op te geven.Gebruik gewoon wat op dat moment 't best werkt.

[DaFeliX]

Ik kijk naar de documentatie, juist ook om te zien of ik wel met die tool wil werken.

Goede documentatie maken is lastig, en helaas lukt dit niet iedereen even goed. En er zal een moment komen dat je die documentatie nodig hebt, dus beter kom je er vroeg achter of die documentatie goed is.

Het probleem met volgen van tutorials is dat je vaak wel leert hoe je een systeem gebruikt, maar leert niet het systeem zelf kennen. Als ik dan wat anders wil dan de tutorial uitlegt, dan kan ik wel raden dat je hier dit moet aanpassen, en daar dat, maar als dat dan niet werkt kan ik het niet debuggen en raak ik gefrustreerd. En hoeveel tutorials leggen nu uit wat jij precies wilt?

In de ideale wereld begin ik daarom bij de documentatie, en pas op 't moment dat ik denk dat ik de tool begrijp ga ik er mee aan de slag. Tutorials gebruik ik dan vooral om inspiratie op te doen hoe je zaken anders zou kunnen doen, maar dan heb ik in elk geval een werkende implementatie conform de documentatie. Tutorials zelf volg ik dan 't liefst in geschreven vorm, omdat die over het algemeen up-to-dater zijn dan video's.

[Furion2000]

@FunkyPeanut
Die 2 cents te samen maken toch al snel een euro/dollar (whatever). Nou dit is tot dusver ook mijn werkwijze en in mijn ogen inderdaad prima als je op een applicatie word gezet waar je snel productief wil zijn in framework x, y en z.

Alleen bij eigen projecten (eigen keus van stack) en de stap naar een mening kunnen vormen en exact weten hoe een framework in elkaar zit, moet je zelf goede afwegingen kunnen maken om niet na 3-4 jaar met een framework te zitten wat er weer uit kan. Vind @DaFeliX mijn probleem goed uitleggen, maar ben wel benieuwd hoe het bij hem is gegaan in de laatste jaren? (lees: niet ideale wereld)

@RobIII Klopt wat je zegt, maar ik wil een beetje van die evenzo random manier van leren af komen

Thanks voor de input!

[DaFeliX]

Furion2000 schreef op maandag 21 maart 2022 @ 08:38:
@FunkyPeanut
[...] Vind @DaFeliX mijn probleem goed uitleggen, maar ben wel benieuwd hoe het bij hem is gegaan in de laatste jaren? (lees: niet ideale wereld)
[...]

Wisselend Zelfs met de aanpak van het zorgvuldig selecteren van een framework is het mij wel 'ns gebeurd achteraf tot de conclusie te komen dat 't niet de juiste keuze leek te zijn.
Voor mijn ervaringen met 'tutorial-first': Voor een paar kleine projecten is dit goed gegaan, voor de meeste andere minder. Alleen ging het dan altijd om dependencies, die zijn eenvoudiger te wisselen als je er ontevreden over bent

Het gaat specifiek om een framework, dus ik schrijf even vanuit dat perspectief: De keuze van een framework heeft nogal wat impact (want dit wissel je minder makkelijk om voor een ander framework), dus ik zou daar vooral kijken naar de kwaliteit van de documentatie. Zoals eerder gezegd, zodra je iets wil gaan doen wat niet gangbaar is en geen tutorials voor zijn, is het essentieel dat de documentatie je kan helpen. Dat maakt voor mij de kwaliteit van documentatie dan ook heel belangrijk in de keuze van een framework.
Omdat tutorials vaak door anderen worden gemaakt, is er een grote kans dat als je framework niet meer hip is, er geen nieuwe tutorials bijkomen. De kans dat documentatie verslechterd is imo kleiner.

In de praktijk werkt 't bij frameworks bij mij zo: Ik lees eerst de introductie van de documentatie door om te bepalen wat de visie is van 'n framework. Daarna skim ik door de andere hoofdstukken om te zien of dit aansluit bij wat ik tot dan gelezen heb. Lijkt dit te kloppen en passen bij mijn werkwijze, dan ga ik met een simpel project aan de slag adhv documentatie. Dat is dan het punt waarop je redelijk kunt inschatten hoe goed documentatie echt is, je hebt immers al hands-on ervaring. Dat is volgens mij het punt waarop je ook niet-officiele tutorials kunt gaan volgen om je kennis te verbreden.

Het 'probleem' van deze aanpak is dat je initieel heel veel tijd neemt; veel meer dan het volgen van een tutorial. Volgens mij rechtvaardig je die extra tijd doordat je ook kijkt naar de toekomst, de onderhoudbaarheid van je project. Een tijdsinvestering in 't begin zorgt er dus voor dat de kans dat je later 'vastloopt' kleiner is. Hoe aantrekkelijk het ook moge zijn om adhv een YouTube-tutorial binnen een uur je werk af te hebben, kan het je veel frustratie besparen die je later hebt als 't project niet te onderhouden blijkt te zijn.

Ergo: Als het een deel is dat eenvoudig te vervangen is, tutorial-first kan hier snel resultaat opleveren. Voor een framework zou ik het risico niet nemen

[Furion2000]

Helder, kosten baten afwegen, maar toch wel documentatie first hanteren

[bwerg]

DaFeliX schreef op maandag 21 maart 2022 @ 07:37:
Het probleem met volgen van tutorials is dat je vaak wel leert hoe je een systeem gebruikt, maar leert niet het systeem zelf kennen. Als ik dan wat anders wil dan de tutorial uitlegt, dan kan ik wel raden dat je hier dit moet aanpassen, en daar dat, maar als dat dan niet werkt kan ik het niet debuggen en raak ik gefrustreerd. En hoeveel tutorials leggen nu uit wat jij precies wilt?

Je noemt het een probleem, maar het doel van een tutorial is gewoon heel anders dan dat van een documentatie. Een tutorial moet een concreet en makkelijk te volgen lineair introductie-verhaaltje zijn, terwijl een documentatie een volledig overzicht moet geven, inclusief alle details, doorgaans in een niet-lineaire vorm.

Een tutorial is om gewoon even lekker een half uurtje te gaan lezen/kijken, maar je moet niet verwachten dat je precies vindt waar je behoefte aan hebt. Documentatie is om op te zoeken, als het goede en volledige documentatie is staat er wel precies in wat je wil maar je mag zelf zoeken waar en je mag zelf de juiste context vinden. Natuurlijk zit er in documentatie ook wel eens een introductie-pagina of een globaal overzicht, maar dat sluit aan bij de opmerking "de ene documentatie is de andere niet", die scheiding is natuurlijk niet binair.

Het doel van een framework is weer iets wat niet inherent per se in een tutorial of documentatie zal staan. De maker van de tutorial of van de documentatie kan zich best richten op een publiek dat de keuze voor een framework al gemaakt heeft. Al is het wel een inkopper om het doel wel te vermelden (dus: welk probleem lost dit framework op, en welke niet, en waarom dit framework en niet de concurrent), het is wel onderwijskunde les 1 dat je met dat soort dingen begint. Maar mensen die documentatie of tutorials schrijven zitten vaak diep in de stof en hebben dat al in hun hoofd, en staan er niet bij stil dat hun lezer/kijker dat wil weten in plaats van meteen de technische details.

Overigens zijn youtube-tutorials (niet alleen voor programmeren maar voor echt alles) in het algemeen populair maar ik vind het echt waardeloos. Je kunt er niet op je eigen tempo doorheen en je kunt er vooraf maar heel moeilijk even in 1 minuut doorheen klikken om te zien of het wat is. Dan wil ik op zijn minst een overzichtje met klikbare hoofdstukjes o.i.d., maar doe liever een tekst met screenshotjes of embedded mini-filmpjes.

[Furion2000]

bwerg schreef op woensdag 23 maart 2022 @ 09:01:
[...]

Je noemt het een probleem, maar het doel van een tutorial is gewoon heel anders dan dat van een ...

Ik lees hier vooral veel over missconceptie en wat niet, maar wat doe jij dan wel? Of hoe pak jij het aan?

Zijn er ook mensen die gewoon de code doorlopen van een framework/library?

[ Voor 3% gewijzigd door Furion2000 op 23-03-2022 13:12 ]

[bwerg]

Goed punt, het was niet echt een antwoord op de vraag. Het antwoord is helaas denk ik toch gewoon wat @RobIII al aangeeft, dat ligt er maar helemaal aan wat je tegenkomt. Heel goede documentatie heeft behalve alle technische details ook nog een uitleg van het grotere plaatje, dat zou kunnen werken. Als de pagina's gewoon een lijst van beschikbare functies is dan kan het nog zo goed en volledig zijn, maar dan is dat gewoon niet waar je wil beginnen. Code doorlopen zou ik nooit doen, een framework of library gebruik ik juist zodat ik zelf niet meer over de code hoef na te denken, enkel over het gebruik. En hetzelfde voor tutorials: dat kan een prachtige uitleg zijn of gewoon een verhaaltje van een persoon die gewoon iets leuks heeft gebouwd en dat laat zien, dat laatste is doorgaans voor de meeste lezers niet nuttig.

TLDR: gewoon googelen, en zien of je iets prettigs tegenkomt.