Anti-patronen in Software Blogging

In softwareontwikkeling verzamelen we anti-patronen om veelvoorkomende kenmerken te herkennen die leiden tot slechte resultaten in onze software. Ik dacht dat het nuttig zou zijn om hetzelfde te doen voor software blogging, dus heb ik de meest voorkomende fouten die ik zie bij beginnende bloggers gecatalogiseerd.

De dwalende inleiding

De meest voorkomende fout in software blogging is dwalen. Ik merk constant dat ik verschillende alinea's in een bericht ben gedoken zonder dat ik weet wat de auteur mij probeert te vertellen.

Ontwikkelaars houden van specificiteit, dus beginnen ze blogposts vaak met achtergrondinformatie, historische context en alles wat hen op dat moment in de zin komt. Dat is misschien leuk om te schrijven, maar het is niet altijd interessant om te lezen.

Vanuit het perspectief van de lezer zijn er een miljard andere artikelen die ze zouden kunnen lezen. Waarom zouden ze die van jou lezen? Ze zullen er niet 20 minuten in investeren, tenzij ze een resultaat verwachten. Geef de lezer een reden om door te lezen.

Wanneer een ontwikkelaar een blogpost begint te lezen, proberen ze zo snel mogelijk antwoord te krijgen op twee vragen:

1. Is de auteur dit geschreven voor iemand zoals ik?
2. Wat heb ik eraan om dit te lezen?

Geef jezelf de titel en de eerste drie zinnen om beide vragen te beantwoorden.

Het voordeel dat je biedt kan het aanleren van een nieuwe vaardigheid zijn, het uitleggen van een concept, het illustreren van een nieuw perspectief of het leveren van een vermakelijke tirade. Je moet de lezer simpelweg iets bieden. Ze gaan je blogpost niet lezen alleen omdat hij er staat.

Hier is een voorbeeld van een artikel dat direct ter zake komt:

✓ Goed: Begin een bericht door te laten zien hoe de lezer er baat bij heeft Titel: A Simple Way to Write Better Go Tests "Er is een uitstekend Go-testpatroon dat te weinig mensen kennen. Ik kan het je in 30 seconden leren."

De inleiding communiceert beknopt dat het artikel relevant is voor programmeurs die de programmeertaal Go gebruiken, en de waarde is dat ze snel een nieuwe techniek kunnen leren.

Inleidingen tellen ook mee als 'dwalen'

Sommige bloggers schrijven een boeiende introductie, maar vervuilen het pad van de lezer met extra's zoals een ondertitel, een biografie, een afbeelding of een beroemd citaat. Je kunt deze dingen toevoegen, maar besef dat ze ten koste gaan van je "budget" om de lezer te inspireren om door te lezen. Alles wat je op het pad van de lezer plaatst, is extra werk dat afbreukt van hun beperkte concentratievermogen.

✗ Slecht: De lezer dwingen door een overmatige inleiding te waden

"De lezer weet alles wat ik weet, behalve dit ene ding"

Effectieve docenten vergelijken nieuwe concepten met iets wat de lezer bekend voorkomt. Bijvoorbeeld, als je Jellyfin zou uitleggen, zou je kunnen zeggen: "Jellyfin is een streamingdienst zoals Netflix, maar dan open-source en privé, zodat niemand je kijkgedrag monitort." Het lastige is om te weten wat de lezer bekend voorkomt.

✗ Slecht: Ervan uitgaan dat de lezer alles weet wat jij weet "In dit artikel introduceer ik Docker aan ontwikkelaars die er nog nooit van hebben gehoord. Docker is eenvoudig. Het is niets meer dan een handige frontend voor Linux cgroups. Oh, je kent jails in *BSD? Docker is de Linux-versie daarvan."

Veel ontwikkelaars willen Docker gebruiken, maar herkennen termen als cgroups, jails of *BSD niet. Ze weten misschien niet eens wat Linux is, zeker niet als ze op zoek zijn naar een introductie in Docker.

In plaats van ervan uit te gaan dat de lezer exact dezelfde kennis heeft als jij, moet je aannames over de achtergrondkennis van de lezer minimaliseren:

✓ Goed: Minimaliseer aannames over de achtergrondkennis van de lezer "Docker is een tool voor het verpakken van je app, zodat deze een consistente, reproduceerbare omgeving heeft waar hij ook draait. Docker stelt je in staat om de omgeving en afhankelijkheden van je app te definiëren in menselijk leesbare tekstbestanden. Deze bestanden leggen de vereisten van je app vast, zodat je precies weet hoe het werkt, zelfs na jaren van aanpassingen door verschillende teams."

Wanneer je een blogpost schrijft, denk dan aan je doelgroep. Wat weten ze? Stel je een vriend of teamgenoot voor die je in het echte leven kent. Maak een lijst van termen die zij zouden herkennen en termen die ze niet zouden kennen. Lees je blogpost daarna opnieuw en denk bij elke technische term of je referentiepersoon dit zou begrijpen.

"Je beschrijft het publiek dat ik in gedachten had, maar ik heb nooit geprobeerd op te schrijven wat dat publiek precies weet. Het vergelijken van je lijst met de aannames in mijn concept is echt een eye-opener."

– Tyler Cipriani, tijdens het bewerken van "The future of large files in Git is Git"

Te veel vertrouwen op links

Wanneer heb je voor het laatst een boek gelezen dat je vroeg om te stoppen met lezen, een ander boek te kopen, dat volledig te lezen en daarna pas verder te gaan met het oorspronkelijke boek? Softwarebloggers doen dit voortdurend, hoewel het subtieler is.

Bloggers willen vaak een term noemen die de lezer misschien niet kent, maar hebben geen zin om deze zelf uit te leggen. In plaats daarvan plaatsen ze een link op de term en denken: "Probleem opgelost!"

Het probleem is echter niet opgelost, omdat de lezer zijn flow niet wil onderbreken om een volledig andere website te bezoeken, alleen maar om één woord te begrijpen.

✗ Slecht: Vertrouwen op links om termen aan de lezer uit te leggen "Wijs firewall-regels toe om te voorkomen dat extern verkeer je database bereikt."

De FreeBSD-handleiding die hierboven is gelinkt is een uitstekende bron, maar het hoofdstuk over firewalls is ongeveer 20.000 woorden lang. Wanneer je naar zo'n tekstrijke pagina linkt, leg je een enorme hoeveelheid werk bij de lezer neer.

In plaats van te vertrouwen op een link om het werk voor je te doen, geef je de lezer de minimale uitleg die nodig is om je artikel te begrijpen.

✓ Goed: Vat de relevante informatie achter een link samen "Een firewall is een systeem dat beperkt hoe hosts en netwerken communiceren met een app. Je kunt de beveiliging van je web-app verhogen door firewall-regels te configureren die inkomende verzoeken naar je databaseserver alleen toestaan wanneer ze afkomstig zijn van je app-server."

Link gerust naar nuttige bronnen, maar maak ze een bonus in plaats van een vereiste. Houd de lezer op de pagina. De doelgroep moet in staat zijn om je artikel van begin tot eind te lezen en te begrijpen zonder op links te klikken.

De 'sequel injection' bug

Tegenwoordig is alles een vervolg of een reboot, inclusief blogposts. Ik zie veel blogposts die zo beginnen:

"In deel één hebben we geleerd over quintuply linked lists en hoe ze je dagelijkse LOC-output met 100x kunnen verhogen. In de post van vandaag laat ik je zien hoe goto-statements je laten scrunkmaxen (een term die ik in deel één heb bedacht – weet je hem nog?)."

Het spijt me je te moeten vertellen, maar de meeste lezers hebben deel één niet gelezen. Als je ervan uitgaat dat je vorige artikel nog vers in het geheugen van de lezer zit, denken ze: "Oh, moet ik nu eerst extra werk doen om überhaupt te kunnen beginnen met lezen?"

Het is prima om naar je vorige berichten te verwijzen, maar doe dit niet direct aan het begin. Wanneer je wel naar eerdere posts linkt, vat dan samen wat relevant was in plaats van de lezer te dwingen terug te gaan en het volledig te lezen.

Als je schrijft over een hobby-besturingssysteem dat je vanaf nul hebt gebouwd, dan heb je waarschijnlijk inderdaad meer dan één blogpost nodig. Maar de overgrote meerderheid van de vervolgposts zou met ongeveer 3% meer moeite een op zichzelf staand artikel kunnen zijn.

Overmatige formaliteit

Beginnende softwarebloggers lijden aan de collectieve waan dat je in een stijve, overdreven formele manier moet schrijven om serieus genomen te worden:

"Er werden diverse statische analyse-tools aangewend door mijn teamgenoten en mijzelf gedurende de gehele levensduur van dit project."

Je schrijft niet voor 80-jarige managers bij IBM in 1988. Je vakgebied is softwareontwikkeling, een van de minst pretentieuze kantoorbanen die er zijn. De persoon die je artikel leest, draagt waarschijnlijk een pyjama en slippers terwijl hij uit een kom cornflakes eet naast zijn toetsenbord. Ze verwachten of willen niet dat je praat als een juridisch document.

Schrijf gewoon zoals je praat.

✓ Goed: Schrijf zoals je praat "We hebben een paar statische analyzers geprobeerd in dit project."

Omdat zoveel ontwikkelaars hun schrijfwerk delegeren aan AI, wordt software blogging saai en homogeen. Lezers snakken naar teksten met persoonlijkheid. Hier is een willekeurige zin van Joel Spolsky, de beste softwareblogger aller tijden:

"Alle kinderen die op de middelbare school uitblonken door pong-games in BASIC te schrijven voor hun Apple II, gingen naar de universiteit, volgden CompSci 101 en een cursus datastructuren, en zodra ze bij de pointers kwamen, explodeerden hun hersenen volledig, en voor je het wist, studeerden ze Politieke Wetenschappen omdat de rechtenstudie een beter idee leek."

– Joel Spolsky, “The Perils of JavaSchools”

Het is niet Spolsky's beste zin, maar het vangt zijn stijl. Het is informeel, persoonlijk en onpretentieus. Het klinkt alsof hij een verhaal vertelt aan vrienden tijdens de lunch. Dezelfde stijl zie je terug in het werk van Kathy Sierra, Terence Eden en Raymond Chen. Ze proberen niet slim over te komen – ze proberen gewoon zichzelf te zijn, en dat is wat lezers waarderen.

Blunders bij de basis van HTML-rendering

Het moeilijkste deel van software blogging is het overtuigend schrijven, dus het is frustrerend om te zien dat zoveel softwarebloggers de mist in gaan bij het deel dat makkelijk zou moeten zijn: het maken van een basiswebpagina.

Pagina-overflow op mobiel

De ergste fout die je kunt maken voor mobiele lezers is de pagina laten 'overvloeien', waardoor de lezer horizontaal moet scrollen om je artikel te kunnen lezen. Meestal komt dit door een afbeelding of code-snippet die vastvastzit op desktopformaat en de lay-out van de rest van de pagina verpest.

Het toestaan van tekst die over het scherm loopt op mobiel creëert een verschrikkelijke leeservaring.

Desktopversies van Firefox en Chrome hebben beide een mobiele preview-modus. Controleer je artikel met deze preview voordat je het publiceert en check op veelvoorkomende rendering-problemen. Onderschat je mobiele lezers niet. Volgens mijn analytics leest 25% van jullie deze pagina op hun telefoon; op mijn persoonlijke blog is dat zelfs 35%.

Onleesbaar lettertype

Kies een letterkleur en een lettertype die gemakkelijk te lezen zijn. Stop met dat donkergrijze tekst op een lichtgrijze achtergrond. Firefox en Chrome hebben beide ingebouwde tools die tekst met een laag contrast voor je signaleren.

Als je geen zin hebt om te zoeken naar het perfecte lettertype, heeft het Braille Institute een gratis lettertype genaamd Atkinson Hyperlegible dat bijzonder comfortabel is om te lezen, zelfs voor lezers met een visuele beperking.

Samenvatting

• Geef de lezer een overtuigende reden om door te lezen. Doe dit in de titel en de eerste drie zinnen van je blogpost. Veelvoorkomende redenen zijn: een vermakelijk verhaal horen, een nuttige techniek leren of een relevant concept begrijpen.
• Bevraag je aannames over wat de lezer weet en niet weet. Denk na over welke concepten en termen de lezer herkennen zou moeten en lees je artikel opnieuw om te controleren of dit overeenkomt met die verwachtingen.
• De lezer moet je artikel van begin tot eind kunnen lezen zonder op links te klikken of over tooltips te hoeven zweven. Links moeten de lezer in staat stellen om onderwerpen dieper te verkennen, maar ze moeten een bonus zijn en geen vereiste.
• Vermijd het presenteren van je artikel als een vervolg op een vorig artikel. Ga ervan uit dat de meeste lezers je vorige artikelen niet hebben gelezen. Vat samen wat relevant is in plaats van te verwachten dat de lezer alle voorgaande posts leest.
• Laat de formaliteit varen. Schrijf zoals je in het echte leven spreekt.
• Test je artikelen in de mobiele weergave van je browser. Zorg ervoor dat de tekst niet over het scherm loopt en de lezer dwingt om horizontaal te scrollen.
• Gebruik browser-testtools om tekst met een laag contrast te vinden die je artikel moeilijk leesbaar maakt.