Het artikel behandelt de neiging van ontwikkelaars om gebrekkige documentatie te schrijven en de moeilijkheid om eigen 'blinde vlekken' in instructies te herkennen. Om dit aan te pakken, heeft de auteur een experiment uitgevoerd voor ActivityBot waarbij hij vrijwilligers betaalde om de README te volgen terwijl ze hun scherm deelden en hardop dachten.
De belangrijkste bevindingen waren:
- Er waren technische fouten (zoals onjuiste links).
- Terminologie en instructies waren voor buitenstaanders vaak onduidelijk of verwarrend.
- De structuur van de documentatie was niet logisch.
De auteur concludeert dat echte menselijke feedback onmisbaar is. Hoewel LLM's simulaties kunnen uitvoeren, bieden echte mensen unieke perspectieven en emotionele signalen (zoals frustratie) die cruciaal zijn voor het creëren van echt bruikbare documentatie.
Ik betaalde mensen om mijn README te proberen te volgen
Ik geloof naïef dat er een betere manier is. Zoals ik eerder heb geschreven, zou je echt je README moeten testen. Start een schone Virtual Machine, loop door wat je hebt geschreven en kijk of het logisch is.
Maar het is erg moeilijk om je eigen blinde vlekken te negeren. Natuurlijk weet je dat bepaalde commando's sudo vereisen, en dat je bedoelde --foo toen je -foo schreef, en iedereen weet natuurlijk dat je daarna moet herstarten.
Hoe kom je van die blinde vlekken af? Ik heb mensen betaald!
Het experiment
Als onderdeel van mijn NLnet-subsidieaanvraag voor ActivityBot gaf ik aan dat ik de installatie-ervaring wilde testen met echte gebruikers. Ik was bereid hen €25 te betalen voor een uur van hun tijd. Ik plaatste een oproep op Mastodon, verzamelde een paar mensen en hield videogesprekken met hen.
Het format was eenvoudig. Ik legde uit dat ik op zoek was naar feedback over de eerste gebruikerservaring. Ik wist dat het niet perfect was en wilde juist constructieve kritiek. Ik vroeg de vrijwilliger om hun scherm te delen en, cruciaal, om hardop te denken. Vertel me wat je doet. Wat begrijp je niet, wat verwart je, wat bevalt je en wat frustreert je?
Ik maakte handmatig aantekeningen (want ik weiger alles aan een machine te voeren) en besteedde verschillende uren aan het horen welke onjuiste aannames ik had gedaan.
Belangrijkste ontdekkingen
Onder de hoogtepunten van de feedback vond ik het volgende:
- De link naar de demo-tool was onjuist.
- Sommige mensen lezen een README direct in de terminal.
- Wat betekent het precies om een bestand te hernoemen?
- Hoe hernoem je een verborgen bestand?
- Moet een demo-tool beschikbaar zijn op het web of alleen op de lokale machine van de gebruiker?
- Waarom moet sommige tekst expliciet tussen aanhalingstekens staan en andere niet?
- Mijn grappen zijn niet grappig en werken juist verwarrend.
- Sommige technische termen hadden uitleg nodig.
- De volgorde van de verschillende secties was verwarrend.
- Ik had eigenlijk niet uitgelegd wat de software precies doet.
- Een hele sectie die technisch interessant voor mij was, was volslagen onbegrijpelijk voor iedereen.
- Niet alle webservers gaan op dezelfde manier om met permissies.
Na elke sessie heb ik de README bijgewerkt op basis van wat mensen lastig vonden, om het vervolgens opnieuw te testen met de volgende persoon. In totaal heb ik ongeveer €150 betaald om een groep mensen mij recht in mijn gezicht te laten bekritiseren. Dat is goedkoper dan therapie, toch?
De waarde van echte mensen
Ik weet dat iemand zal vragen: "waarom niet gewoon een LLM vragen om een reeks gebruikers te simuleren?" Het antwoord is heel eenvoudig: ik wil met echte mensen praten. Mensen zijn geweldig! Ze kunnen je aan het lachen maken, je ziet hun kat wanneer die tijdens de call langsloopt, ze brengen een uniek perspectief in op het probleem en ze zijn echt blij als je ze een voucher van €25 geeft. Sommigen doen het zelfs graag gratis.
Toen ik technische teksten schreef voor GOV.UK, werd al mijn mooie proza nagekeken door een ander mens. Zij haalden alle bloemrijke zinnen eruit en maakten het document leesbaarder. Zij waren degene die de fouten ontdekten waar geen enkele spellingscontroleer op zou letten. Ze konden een echt gesprek met me voeren. Belangrijker nog: ik kon de frustratie in hun stem horen – en dat is precies wat je laat weten dat een fout gecorrigeerd moet worden.
Ik beweer niet dat de README van ActivityBot nu perfect is – daarvoor is hij nog lang niet – maar hij is nu aantoonbaar gemakkelijker te volgen. Ontwikkelaars moeten met echte mensen praten. Je hoeft ze niet te betalen als je dat niet kunt veroorloven, maar zoek een paar mensen die hardop praten terwijl ze proberen je instructies te volgen. Ik garandeer je dat je README er veel beter van wordt.
Ik betaalde mensen om mijn README te proberen te volgen
Ik geloof naïef dat er een betere manier is. Zoals ik eerder heb geschreven, zou je echt je README moeten testen. Start een schone Virtual Machine, loop door wat je hebt geschreven en kijk of het logisch is.
Maar het is erg moeilijk om je eigen blinde vlekken te negeren. Natuurlijk weet je dat bepaalde commando's sudo vereisen, en dat je bedoelde --foo toen je -foo schreef, en iedereen weet natuurlijk dat je daarna moet herstarten.
Hoe kom je van die blinde vlekken af? Ik heb mensen betaald!
Het experiment
Als onderdeel van mijn NLnet-subsidieaanvraag voor ActivityBot gaf ik aan dat ik de installatie-ervaring wilde testen met echte gebruikers. Ik was bereid hen €25 te betalen voor een uur van hun tijd. Ik plaatste een oproep op Mastodon, verzamelde een paar mensen en hield videogesprekken met hen.
Het format was eenvoudig. Ik legde uit dat ik op zoek was naar feedback over de eerste gebruikerservaring. Ik wist dat het niet perfect was en wilde juist constructieve kritiek. Ik vroeg de vrijwilliger om hun scherm te delen en, cruciaal, om hardop te denken. Vertel me wat je doet. Wat begrijp je niet, wat verwart je, wat bevalt je en wat frustreert je?
Ik maakte handmatig aantekeningen (want ik weiger alles aan een machine te voeren) en besteedde verschillende uren aan het horen welke onjuiste aannames ik had gedaan.
Belangrijkste ontdekkingen
Onder de hoogtepunten van de feedback vond ik het volgende:
- De link naar de demo-tool was onjuist.
- Sommige mensen lezen een README direct in de terminal.
- Wat betekent het precies om een bestand te hernoemen?
- Hoe hernoem je een verborgen bestand?
- Moet een demo-tool beschikbaar zijn op het web of alleen op de lokale machine van de gebruiker?
- Waarom moet sommige tekst expliciet tussen aanhalingstekens staan en andere niet?
- Mijn grappen zijn niet grappig en werken juist verwarrend.
- Sommige technische termen hadden uitleg nodig.
- De volgorde van de verschillende secties was verwarrend.
- Ik had eigenlijk niet uitgelegd wat de software precies doet.
- Een hele sectie die technisch interessant voor mij was, was volslagen onbegrijpelijk voor iedereen.
- Niet alle webservers gaan op dezelfde manier om met permissies.
Na elke sessie heb ik de README bijgewerkt op basis van wat mensen lastig vonden, om het vervolgens opnieuw te testen met de volgende persoon. In totaal heb ik ongeveer €150 betaald om een groep mensen mij recht in mijn gezicht te laten bekritiseren. Dat is goedkoper dan therapie, toch?
De waarde van echte mensen
Ik weet dat iemand zal vragen: "waarom niet gewoon een LLM vragen om een reeks gebruikers te simuleren?" Het antwoord is heel eenvoudig: ik wil met echte mensen praten. Mensen zijn geweldig! Ze kunnen je aan het lachen maken, je ziet hun kat wanneer die tijdens de call langsloopt, ze brengen een uniek perspectief in op het probleem en ze zijn echt blij als je ze een voucher van €25 geeft. Sommigen doen het zelfs graag gratis.
Toen ik technische teksten schreef voor GOV.UK, werd al mijn mooie proza nagekeken door een ander mens. Zij haalden alle bloemrijke zinnen eruit en maakten het document leesbaarder. Zij waren degene die de fouten ontdekten waar geen enkele spellingscontroleer op zou letten. Ze konden een echt gesprek met me voeren. Belangrijker nog: ik kon de frustratie in hun stem horen – en dat is precies wat je laat weten dat een fout gecorrigeerd moet worden.
Ik beweer niet dat de README van ActivityBot nu perfect is – daarvoor is hij nog lang niet – maar hij is nu aantoonbaar gemakkelijker te volgen. Ontwikkelaars moeten met echte mensen praten. Je hoeft ze niet te betalen als je dat niet kunt veroorloven, maar zoek een paar mensen die hardop praten terwijl ze proberen je instructies te volgen. Ik garandeer je dat je README er veel beter van wordt.
Groetjes,