Individueel Blog+Presentatie als team

Introductie/TL; DR

Doe een onderzoek naar een DevOps technologie en schrijf hier (individueel) een blogpost over en geef een korte presentatie (in teamverband). Onderzoek hierbij een DevOps tool die hoort bij een van de onderwerpen van de workshops en lessen uit de course fase. Je mag er zelf een kiezen, waarover je graag nog meer zou willen weten. Kijk hierbij ook vooruit naar de eindopdracht, en technologie die je hierbij kan helpen om een hoger niveau uit het CDMM te halen.

Technologie is een vrij algemene term, maar dit is bewust. Regelmatig is dit een DevOps Tool, zoals CRIO of , maar de technologie mag ook een een framework of library zijn of zelfs programmeertool. Het kan ook een 'standaard' zijn, zoals bv. toml. Maar omdat je onderzoek ook een 'hands-on'/praktisch karakter moet hebben is het wel goed om hier ook een tool bij te zoeken.

Schrijf een blogpost samen met ChatGPT. Verifieer deze daarna met andere bronnen, en zorg dat je zelf het begrijpt. Herschrijf en vul aan met met andere (online) bronnen, en schrap vooral gedeelten die niet kloppen of wollig zijn. Voeg een stuk hands-on toe, in vorm van tutorial volgen en stukken code of config schrijven.

Je geeft ook een korte presentatie waarin je laat zien dat je het begrijpt. Dit is een 'pitch' van deze DevOps technologie. Orienteer je ook of de technologie samenwerkt met andere technologieen die teamgenoten daar gaan gebruiken/introduceren. Bedenk een hoofdvraag en deelvragen en vind hierbij onderzoeksmethoden.

Welke onderwerpen?

Kortgezegd kun je een DevOps tool uit het CNCF landschap pakken. En deze koppelen aan een concept uit CDMM, of ander concept of DevOps credo of buzzword.

  • Per groep moet er minstens 1 persoon zijn die een onderwerp rondom SlackOps onderzoekt (wegens vervallen Prometheus)
  • Het kan zijn dat er een onderwerp in de workshops was waarover jij niet zo veel nieuws hebt geleerd (omdat je die kennis al in huis had), maar waarvan je toch nog wat meer zou willen weten.
  • Het kan ook zijn dat je een workshop hebt gehad waarvan je juist heel veel geleerd heeft, maar die je extra goed duidelijk wilt krijgen en og meer wil weten.
  • Het kan ook nog zo zijn dat je in een combinatie van onderwerpen uit de workshops een mogelijkheid ziet om jezelf verder te verdiepen.

Doelgroep

Welk onderwerp je ook kiest: het is de bedoeling dat je je op dat onderwerp verder gaat verdiepen en dat je daarover een blog post (een stuk tekst) produceert die aansluit op het niveau van de minorcourse. De blog post moet te begrijpen zijn door je klasgenoten (peers) en hen ook nieuwe info moeten geven. Maar de tekst ook te begrijpen door buitenstaanders met hetzelfde kennisniveau als je klasgenoten (ICT'ers), maar die de minor niet volgen. Dus geef ook wat korte context van de minor waar je in zit. Dit kan met één zin en een linkje.

Je schrijft dus een verhaal met een kop en een staart: inleiding, kerntekst en conclusie (AIM controlekaart). In een blogpost is dit echter wel wat vrijer, dus — anders dan in een onderzoeksverslag - gebruik je niet letterlijk deze kopjes. Maar je deelt het wel in drieen. Je gebruikt ook bronnen en refereert hiernaar met een quote of parafrasering, zodat je de lezer niet dwingt de bronnen zelf te lezen (alleen als check).

Lijdende vorm

De AIM controlekaart geeft aan dat je NIET in de lijdende vorm moet schrijven. Dit is de laatste regel, en hier doen studenten vaak niks mee, of ze realiseren zich niet eens precies wat het betekent. In de versie van controlekaart op deze site is regel 11 over de lijdende vorm is herschreven in de actieve vorm, in het kader van "eating your own dogfood":

"Je schrijft het document in de actieve vorm. Het bevat nagenoeg geen lijdende zinnen."

Ook in het bedrijfsleven is regelmatig aandacht voor 'actief schrijven'. Google heeft in hun (online) course over Technical writing ook een prominente plaats gegeven (zie figuur 1).

Ingezoomd: Voetballer chopt tegen bal

Figuur 1: Google Technical writing - 'Active vs passive voice'

Dit voorbeeld geeft mooi aan dat lijdende vorm niet alleen te voorkomt als 'word/worden' + voltooid deelwoord maar ook als 'is/zijn' + voltooid deelwoord. Wel geldt nog dat als je merkt dat je makkelijker schrijft door wel de lijdende vorm te gebruiken, en regel 11 je dus blokkeert, dat het prima is wel lijdend te zchrijven. Zolang je de tekst maar herschrijft vóórdat je deze inlevert. Zoek een keer op 'word' in je tekst, en als het vaker dan 5 keer voorkomt weet je zeker dat je moet gaan herschrijven en de tekst een stukje korter kan.

Zolang de tekst uiteindelijk maar (overwegend) in de actieve vorm staat. Ander is het wollig en vaak onvoldoende duidelijk. De Google course 'Technical writing' is een nieuwere bron die nog eens het nut van schrijven in de actieve vorm uitlegt: "Je geeft meer context".

In een analogie tussen (natuurlijke) tekst schrijven en (programmeer)code schrijven is het ook belang om actief te schrijven om zo responsability te assignen (denk 'Single Responsability' en 'GRASP', etc.)

Een begin: "Er wordt een controle gedaan dat de ingegeven gebruikersnaam bestaat."

Vraag: Door wie? Ga jij bij al die mensen staan met een lijst en tik je ze op de schouder als ze een al bestaande gebruikersnaam ingeven.

Beter: "Het systeem controleert dat..."

Vraag: Welk deel van 'het systeem'? Is dit een front-end controle, of back-end. Front-end is door hackers makkelijk te omzeilen. Belangrijke checks, zoals bestaande gebruikersnaam moet je sowieso dubbel checken ook op de server.

Nog beter: "Bij inloggen controleert de back-end dat..." Vraag: Hoe ziet de code er dan ongeveer uit, gezien we elders kozen voor JAX-RS Restful endpoints..

Uiteindelijk in SDD: "In het REST endpoint op de back-end doet de aan dit endpoint gekoppelde methode login() in de LoginResource een controle dat..."

Nu ga je meer riochting het punt dat een junior developer het met jouw spec moet kunnen implementeren... Oftewel, zoeken naar actieve vorm en expliciet verantwoordelijkheden toewijzen en daarbij je problemen opdelen in deelproblemen helpt je straks in ICT werk ook te gaan richting een team lead, in plaats van een 'code monkey'.

Code Monkey
Figuur 1: Code monkey - Jonath Coulton

Hands-on karakter

In je blog post moet je ook code en/of configuratie beschrijven, dus je blog bevat ook één of meerdere secties aan de hand waarvan de lezer zelf iets kan programmeren, configureren en/of beschreven stappen van toolgebruik kan naspelen. Kies hierbij wel voor 'configuration as code' en/of 'scripting' in plaats van hele handleiding met veel screenshots van te zetten vinkjes in GUI's, omdat dit laatste sneller verouderd.

Link ook naar je repository. Zet deze repository bij voorkeur op GitLab of GitHub (GitHub als deze publiek moet zijn/bewaard mag blijven).

Zorg wel dat je niet alleen hands-on stuk hebt, maar ook de nodige concepten uitlegt en context en introductie in je blog hebt. En natuurlijk ook een conclusie/recap.

Markdown, format en structuur

De blog is geschreven in markdown, met hierin ook gebruik van plaatjes en afwisseling van vrije tekst en gestructureerde vormen als tabellen, bullet lijsten en eventueel grafieken. Sluit aan bij format van bestaande blogs hier op de site. Gebruik ook afbeeldingen in je blog, en zorg dat deze ondersteunen en geef deze figuurnr's (caption), tenzij ze zuiver illustratief zijn. Verwijs in je tekst o.b.v. deze figuurnummers en schrijf ook toelichting bij zaken die vragen kunnen oproepen. Gebruik wel 'Creative Common' plaatjes om problemen met auteursrecht te voorkomen. Zorg ook dat je attributie doet voor de plaatjes, door 'ook bij het gebruik van afbeeldingen de bron te noemen (hier dan ook APA bron voor gebruiken).

De blogpost heeft ook eens structuur met koppen en subkoppen. Eventueel ook nog subsubkoppen, maar niet 'dieper' dan dat, want wat voor code geldt; geldt ook voor schrijven:

"If you need more than three levels [...], you're screwed anyway" - Linus Torvalds, Linux kernel coding style, z.d.

Schrijf de blogpost (net als vorige opdrachten) weer in een prive repo op gitlab. De blog staat direct in de README.md of je linkt vanuit de README.md naar je blogpost.md of <blog-onderwerp-coole-titel-cq-url-slug-voor-seo> omdat je repo ook een apart onderzoeksplan.md met je hoofd- en deelvragen en onderzoeksmethoden en toelichting.

Puntsgewijze samenvatting

  • Schrijf de resultaten van je onderzoek op in de vorm van een blog-post (in het Nederlands! dus geen Engels of anderszins).
  • Het is de bedoeling dat je onderzoek ofwel verbredend is (je betrekt er bijvoorbeeld onderwerpen bij die niet in de workshop zijn behandeld, of je past het onderwerp toe in een heel andere context), ofwel verdiepend is (je gaat dieper in op het onderwerp/de techniek doordat je bijvoorbeeld technischere bronnen aanboort of het onderwerp toepast in een complexere situatie). Een combinatie mag ook. In elk geval moet je duidelijk een toevoeging maken op wat de docent in de lessen behandeld heeft.
  • Een korte introductie van je onderwerp hoort bij je blogpost, maar je mag ervan uitgaan dat de lezers geen “beginners” zijn op het gebied van jouw onderwerp. Ga ongeveer uit van je eigen niveau op het moment dat je met het onderzoek begon. Het eindniveau van de workshops dus, ongeveer.
  • Een korte beschrijving van je onderzoekmethode (eventueel met verwijzingen naar gebruikte methoden zoals die van ictresearchmethods.nl) hoort ook bij je verslaglegging. We verwachten degelijk onderbouwd, traceerbaar en reproduceerbaar werk in je blog.
  • Gebruik bronnen en verwijs hiernaar
    • dat mag door links naar websites op te nemen in je tekst (gebruik waar mogelijk en relevant ook anchors om te verwijzen naar specifieke secties)
    • maar het moet ook met [APA], dus een Bronnen lijst onderaan met al je bronnen (bij ICT meestal webpagina's) (HAN studiecentra 2021-a)
    • en bij APA hoort ook in je blogtekst voor elke bron een quote of parafrase, dus: "in eigen woorden weergeven van andermans werk [...] gevolgd door een verwijzing tussen haakjes met de achternaam van de auteur(s), het jaartal ..." (HAN studiecentra 2021-b).
  • Je tekst moet opgemaakt zijn met Markdown. Dat is later eventueel eenvoudig te converteren naar HTML. Je mag eventueel bijlagen bijvoegen. Deze hoeven niet in Markdown te zijn opgemaakt. Wanneer je gebruik maakt van bijlagen, verwijs hier dan duidelijk naar vanuit de tekst. Wanneer je bijvoorbeeld kleine stukjes code wil toevoegen mag je die gewoon “embedded” opnemen. Voeg uiteraard wel bronvermelding toe wanneer de code niet van je eigen hand is!
  • Je levert je werk in op iSAS en voegt eventuele bijlagen toe door ze samen met het Markdown-bestand in een zip-bestand te zetten en dat in te leveren.
  • We gaan ervan uit dat je in deze week van deze course al je tijd aan deze opdracht besteedt. Dat betekent dus dat het onderzoek, schrijfwerk en voorbereiden presentatie je zo’n 40 uur zou moeten kosten. Dit is inclusief het plannen van je werk, het zoeken naar bronnen, het uitvoeren van experimenten, het uitzoeken en oplossen van technische problemen en het schrijven van je tekst. We verwachten deze tijdsinvestering terug te zien in de complexiteit en/of omvang van je werk.

Beoordelingscriteria onderzoek

Beoordelingsmodel onderzoeks blog

Figuur 1:

Hierboven een screenshot van het beoordelingsformulier uit 2021. De beoordelingscriteria zijn onderverdeeld in de volgende drie categorieën:

  • Onderwerp, diepgang, theorie/praktijk (KO)
  • Helderheid en doelgroepgerichtheid
  • Bronvermelding

Zie iSAS voor de precieze beoordelingsfactoren- en criteria (editie van 2023, check dat link kloot; dit kan jaarlijks licht veranderen)

Kortgezegd schrijf je een blog over je onderzoek naar een onderwerp dat in het verlengde van de minor ligt, met als doelgroep je klasgenoten, dat aansluit bij geleerde theorie en een hands-on karakter waarbij je laat zien dat je goede bronnen hebt geraadpleegden via referentie naar goede bronnen. Maximaal 1500 woorden (ca 3 A4), exclusief bronnen en code, minimaal 800 woorden (2 A4).

Hieronder meer over onderwerp, vorm en inhoud en eisen en werkwijze voor je blogpost en onderzoek.

Onderzochte technologie toepassen in (team!) beroepsproduct

Sta in een eventueel onderzoeksplan ook stil bij de eis voor toepassen van de nu onderzochte technologie in je beroepsproduct de laatste 2 weken. Denk dus vast vooruit naar PitStop en scan hier bv. nog eens doorheen wat er in zit, en bij past.

Overleg idealiter met beoogde teamgenoten voor beroepsproduct. Zij moeten immers ook hun technologie toepassen; dus er moeten een aantal technologieen in de microservces applicatie ‘passen’ die hopelijk ook enigszins aanvullend zijn of ‘orthogonaal’ (onderling onafhankelijk) zijn. Het is nuttig om even over te brainstormen.

Sluit een PACT voor peer feedback in je team

Sluit binnen je team een PACT™ af: dit is de Peer Assessment Circle Tactic™.

Bijvoorbeeld als je team 4 teamleden gaat bevatten: Teamlid 1 --> Teamlid 2 --> Teamlid 3 --> Teamlid 4 --> `Teamlid 1``

Op deze manier hou je peer assessment binnen je groep om elkaars tech vast te leren kennen, maar zorg je ook voor dat NIET jouw assessee ook jouw assessor is, wat ongewenst 'mooi weer spelen' in de hand zou werken. Zachte heelmeesters maken stinkende wonden... (e.g. alles wat uit peer assessment komt, komt beoordelaar niet meer tegen bij echte beoordeling).

Zet de gekregen feedback van je teamgenoot in je onderzoeks repo. Als je de feedback in een mail kreeg of Slack bericht kun je het copy-paste het onderaan in je onderzoeksplan.md. Of als teamgenoot feedback in een issue of je GitHub of Gitlab repo zetten, kun je een link hiernaar toe zetten. Geef in je onderzoeksplan zelf ook aan wat je van deze feedback verwerkt hebt en waarom.

Je teamgenoot kan ook het beoordelingsformullier invullen. Als je dit voor een ander doet kun je hier kritischer mee omgaan, en ook het formulier zelf goed leren kennen, ook voor je eigen presentatie.

Teampresentatie

Op basis van je bevindingen bereid je een korte 'pitch' presentatie voor. Je pitch'ed je onderzochte technologie. Of manier van inzet hiervoor. Deze stem je af met teamgenoten op mogelijke punten waar techniek elkaar aanvult, of juist clashen. Je oefent je pitch op teamgenoten en op de docent.

DOMBLR: DevOps Markdown Blog Linting Rules

In 2024 is een eerste aanzet gemaakt tot een set custom Markdown linting rules, met als doel bepaalde kwaliteitscontroles te automatiseren. Deze linting rules zijn een uitbreiding op standaard Markdown lint (van David Anson, 2024), en zijn specifiek afgestemd op de onderzoeksblogs voor de minor DevOps. Deze helpen bij het waarborgen van consistentie en naleving van de opmaakvereisten.

Status: Work in Progress

Deze linting rules bevinden zich in de onderzoeksrepository en zullen onder andere controleren op:

  • Check op maximaal 1500 woorden (exclusief code blokken)
  • Correcte aanwezigheid van verplichte elementen zoals studentnaam, datum, en startafbeelding.
  • Aangepaste teksten in verplichte afbeeldingen (alt- en title-teksten).
  • Aanbevolen minimale hoeveelheid illustraties ter ondersteuning van de tekst.
  • Structuureisen zoals het gebruik van
    -elementen en overzichtelijke blokken.

Deze geautomatiseerde checks vormen een eerste stap naar een volledige review en zijn vooral bedoeld om standaardproblemen te verminderen. Ze zijn niet bedoeld als een volledige kwaliteitsgarantie, maar helpen wel om de basisvoorwaarden op orde te krijgen.

Code Fluff, plaatje van ChatGPT

Figuur 2: ChatGPT's illustratie van linting: het verwijderen van fluff als metafoor voor het opschonen van code

Meer over de onderzoeksweek

Gebruikte bronnen

Last change: 2025-01-13