Linting Style and Substance in READMEs
Dit paper introduceert LintMe, een aanpasbaar linting-systeem dat programmeerbare controles combineert met LLM-gebaseerde evaluatie om README-documentatie te verbeteren in diverse contexten, terwijl het de auteursvrijheid behoudt.
Oorspronkelijk artikel gelicentieerd onder CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). Dit is een AI-gegenereerde uitleg van het onderstaande artikel. Het is niet geschreven of goedgekeurd door de auteurs. Raadpleeg het oorspronkelijke artikel voor technische nauwkeurigheid. Lees de volledige disclaimer
Stel je voor dat je een nieuw huis bouwt. De README is het bordje voor de deur dat vertelt wat er in het huis zit, hoe je binnenkomt en wat je er mag doen. Vaak is dit het enige wat nieuwe bezoekers zien. Maar wat als dat bordje vol staat met slechte spelling, ontbrekende instructies, of taal die mensen afschrikt? Dan blijft niemand binnen, hoe geweldig het huis ook is.
Dit is precies het probleem dat de onderzoekers van de Universiteit van Utah hebben aangepakt. Ze hebben een nieuw gereedschap bedacht, genaamd LintMe, dat fungeert als een super-veiligheidscontroleur voor deze digitale borden.
Hier is hoe het werkt, vertaald in alledaags taalgebruik:
1. Het probleem: De "Doe-het-zelf" chaos
Tot nu toe waren de hulpmiddelen om teksten te controleren (linters) als een simpele spellingschecker. Die zeggen: "Hier staat een 't' waar een 'd' moet staan" of "Je hebt te veel komma's gebruikt." Ze kijken alleen naar de vorm, niet naar de inhoud.
Maar een goed README moet meer doen dan alleen correct spellen. Het moet vertellen of de code werkt, of er een veiligheidsrisico is, en of de toon vriendelijk is voor iedereen. De onderzoekers merkten dat bestaande tools hier niet goed in waren. Ze zochten naar een manier om ook de diepere betekenis te controleren.
2. De oplossing: LintMe, de slimme kok
Stel je LintMe voor als een slimme kok in een keuken.
- De recepten (Regels): In plaats van dat de kok alles zelf bedenkt, kun je zelf recepten (regels) schrijven. Je kunt zeggen: "Controleer of er een ingrediëntenlijst is" of "Zorg dat de temperatuur in graden Celsius staat."
- De ingrediënten (Operatoren): De kok heeft een setje basisgereedschappen. Hij kan tellen, zoeken, of vergelijken.
- De magische assistent (LLM): Dit is het nieuwe en spannende deel. De kok heeft een super-slimme assistent (een AI) aan de telefoon. Als je de assistent vraagt: "Is deze tekst beleefd genoeg?", kan de AI dat beoordelen. Als je vraagt: "Werkt deze link?", kan de AI dat checken.
Het mooie aan LintMe is dat je deze twee kunt mixen. Je kunt een regel maken die zegt: "Tel hoeveel emoji's er in de tekst staan (dat doet de kok) én laat de AI controleren of de tekst niet te kinderachtig klinkt (dat doet de assistent)."
3. Waarom is dit zo slim? (De drie pijlers)
De onderzoekers wilden drie dingen bereiken, en LintMe doet dit op een creatieve manier:
- Jij bent de chef (Auteur): Je bent niet vastgeketend aan wat de software zegt. Als je denkt: "Voor mijn project is het belangrijk dat er een foto van de machine staat," dan kun je die regel zelf toevoegen. Het is alsof je je eigen keukeninrichting mag aanpassen.
- Iedereen heeft zijn eigen smaak (Gemeenschap): Een recept voor een snelle maaltijd is anders dan een recept voor een 3-gangen diner. Zo is een README voor een wetenschappelijk project anders dan voor een spelletje. LintMe laat groepen hun eigen "standaarden" (presets) maken.
- Jij houdt het roer in handen (Agentie): Veel AI-tools proberen alles automatisch voor je te doen. LintMe zegt: "Ik zie een probleem, ik geef je een suggestie, maar jij beslist of je het aanpast." Het is een gesprek, geen bevel. Je wordt niet gedwongen om fouten te accepteren die je niet begrijpt.
4. De proef in de praktijk
De onderzoekers hebben dit systeem getest op twee manieren:
- Met mensen: Ze gaven 11 mensen (studenten en professionals) de tool. De mensen vonden het geweldig dat ze zelf regels konden maken, maar ze gaven ook toe dat het even duurt om te leren hoe je die regels precies schrijft (een beetje zoals het leren van een nieuw kookboek). Ze merkten op dat het hen hielp om te zien wat ze over het hoofd hadden gezien, zoals een ontbrekende sectie over veiligheid.
- Vergelijking met "domme" AI: Ze gaven dezelfde teksten aan een gewone AI (zonder de slimme regels van LintMe) en vroegen: "Wat is er mis?" De gewone AI zag veel minder fouten. LintMe, met zijn specifieke regels, zag veel meer details, zoals gebroken links of onbeleefde taal. Het bewees dat een gestructureerde aanpak beter werkt dan gewoon "vragen aan de AI".
- De test met recepten: Om te bewijzen dat het systeem flexibel is, hebben ze het gebruikt voor culinaire recepten. Ze maakten regels zoals: "Geen merknamen gebruiken" of "Temperatuur moet een 'F' hebben." Het systeem vond fouten in populaire recepten op internet die zelfs mensen over het hoofd zagen. Dit laat zien dat het werkt voor alles, van software tot kookboeken.
Conclusie
LintMe is als een slimme, meedenkende redacteur die niet alleen kijkt naar spelling, maar ook naar de inhoud, de structuur en de sfeer van je tekst. Het geeft je de macht om je eigen regels te stellen, terwijl het je helpt om te zien wat je misschien hebt gemist.
In plaats van dat een computer zegt: "Dit is fout, ik maak het wel even goed," zegt LintMe: "Kijk hier eens naar, dit lijkt me niet helemaal goed voor jouw doel. Wil je het aanpassen?" Het maakt het schrijven van betere documentatie een samenwerking tussen mens en machine, waarbij de mens de baas blijft.
Verdrinkt u in papers in uw vakgebied?
Ontvang dagelijkse digests van de nieuwste papers die bij uw onderzoekswoorden passen — met technische samenvattingen, in uw taal.