Onderzoek: Toelichting en tips bij schrijven

In week 6 verdiep je je in een DevOps technologie en schrijft hier een eigen blogpost over.

Vanwege het verplicht 'hands-on' karakter kies je als onderwerp dus een redelijke concrete tool, framework en niet een heel algemeen onderwerp. Dus kies bijvoorbeeld 'Google Cloud AI Platform' in plaats van 'Artificial Intelligence'. Je blog post moet een hands-on karakter hebben. Er moet ook (voorbeeld) code of configuratie in je blog post voorkomen.

Maar je geeft elkaar ook onderling feedback. Je vormt ook vast de teams voor de eindopdracht volgende week en zorgt dat de te onderzoeken technologieen op de een of andere manier op elkaar aansluiten. Dat deze ook bruikbaar zijn tijdens realisatie van beroepsproduct in de 2 laatste weken van de course.

Hieronder verdere informatie, zoals knock-outs, suggesties voor onderwerpen/technologieen, tips.

1. Knock-outs

  • Je bent niet bij de groepspresentatie of hier blijkt dat je niks hebt onderzocht of voorbereid
  • Je hebt geen duidelijke en beschrijvende titel voor je blog (laat staan 'pakkend')
  • Blog post NIET in markdown/tekst format, geen (extra) code in je repo (waar je naar verwijst)
  • Geen code of configuratie in je blog post (deze moet 'hands-on' zijn)
  • Er zit geen goede plaatjes in je blog (zelfs niet een paar)
  • Te veel gebruik passieve vorm (zeg >= 5x 'wordt' in je tekst) of toekomende tijd
  • Je blog is te veel een reclamepraatje: veel onuitgelegde bijvoeglijke naamwoorden of bijwoorden
  • Geen goeie introductie (denk ook aan de leeswijzer hierin (=geen kopje!))
  • Geen conclusie/afsluiting
  • Als je een onderzoeksverslag hebt geschreven in plaats van een blog
  • Geen goede structuur; niet opgesplitst in logische secties en evt. subsecties
  • Minder dan 800 woorden, of (veel) meer dan 1500 woorden (exclusief config/code)
  • Minder dan 5 referenties naar externe bronnen (en/of niet goed conform APA, zoals geen referenties in de tekst naar (al) je bronnen)

2. Voorbeelden van onderwerpen voor je onderzoek

Hieronder een lijst van mogelijke/geschikte onderwerpen, als er bij je zelf geen inspiratie/prangende onderzoeksvraag is ontstaan tijdens de voorgaande course weken. Kijk ook eens naar de onderwerpen op de 'not list' uit de minor chartering.

OPS

  • runc
  • ContainerD
  • K3S/Rancher
  • LXC/LXD
  • Portshift, Pod scanning
  • Terraform
  • Build bakery

Dev

  • Istio
  • gRPC
  • LinkerD
  • Grafana
  • Event sourcing
  • Chaos engineering met Gremlin
  • SonarQube
  • Helm
  • Crio
  • Rancher
  • K3S
  • Prometheus (log/statistics)
  • linkerD (service mesh)

Dev of Ops

  • Kubernetes Custom Resources
  • Services Meshes en Istio (of LinkerD)
  • Kubernetes security en container scanning
  • Secret management en certificates
  • Site Reliability Engineering (SRE)
  • AKS vs on premise K8S

3. Onderzoeksplan schrijven (optioneel, maar aangeraden)

Voor de blogpost is de eis dat je je eigen unieke onderwerp kiest binnen de klas. Om echt de volle week te gebruiken en niet te stranden moet je het gewenste onderwerp voor aanvang van de onderzoeksweek al gekozen hebben. En ook een reserve onderwerp. Op maandag, met hulp van een workshop schrijf je hierbij een onderzoeksplan met een concrete hoofdvraag en bijbehorende deelvragen (minimaal 3 en maximaal 7). Je hebt ook nagedacht over de te gebruiken onderzoeksmethode en sluit aan bij de ICT onderzoeksmethoden (die HAN medewerkers mede ontwikkelden).

Dit laatste doe je door voor elke deelvraag een geschikte onderzoeksmethode te vinden/kiezen en te benoemen. Maak hierbij NIET de veelgemaakte fout om onderzoeksmethode te verwarren met onderzoeksruimte ('lab' is bv. GEEN onderzoeksmethode, maar een -ruimte met hierbinnen meerdere methoden zoals 'component test' en 'unit test') (zie figuur 1). Varieer wel in onderzoeksruimte voor de triangulatie (DOT framework). De focus tijdens onderzoek ligt op Lab en Workshop onderzoek. Field onderzoek gebeurt meer tijdens ontwikkelen van beroepsproduct. De zogenaamde 'triangulatie' uit de 'DOT Framework' die achter de de ICT onderzoeksmethoden zit.

Met je onderzoeksplan zorg je dat je ook echt vragen stelt, en beantwoord en trianguleert. Deze kijken we niet per se na, maar bij twijfel over de kwaliteit kan beoordelaar dit erbij pakken. Een prima onderzoeksplan kan een twijfelachtige blogpost toch het voordeel van de twijfel geven.

Figuur 1: Overzicht van onderzoeksmethoden (deel ervan, bron: /methods-overview, 2023)

Je mag ook de joker gebruiken. Je kunt de onderzoeksmethoden een beetje vergelijken met 'patterns', het is een naam voor een aanpak van een veelvoorkomende type probleem. Zorg dat je ook echt iets met deze aanpak doet door ook de ingredienten te gebruiken. Dus in plaats van (alleen) een tabel of bullet list te geven van je onderzoeksvragen en voor elk de gebruikte onderzoeksmethode, schrijf je ook gewoon een stuk vrije tekst om dit uit te leggen

Als je de joker in zet is het het sterkst is natuurlijk als je je eigen onderzoeksmethode dan een naam geeft. Hoewel je in het 1e jaars wellicht nog wel een introductie bij de bibliotheek hebt gehad, gebruikt eigenlijk 100% van de studenten uitsluitend internet als bron. Oftewel googlen. Je kunt ook de CMD onderzoeksmethoden. Maar noem/kies ook concrete 'en relevante ingredienten' uit de gekozen onderzoeksmethode.

De deliverable van je onderzoek is GEEN onderzoeksverslag, maar een blog post. Dus met minder formeel taalgebruik. Een onderzoeksplan is ook niet verplicht, maar kan je zelf wel helpen. En het wel aanwezig zijn (van bv. een onderzoeksplan.md in je repo) is een goede safeguard mocht je onderzoek toch tegen vallen (ook bewijsmateriaal voor beoordelaar).

4. Vooronderzoek

Voordat je een onderzoek start, moet je wel wat vooronderzoek doen om de goede vraag te kunnen stellen. Om een idee te hebben of je een vraag in een middagje kunt beantwoorden (te klein, wellicht een deelvraag van maken of scope uitbreiden) of dat het wellicht maanden duurt (te groot, deel aspect pakken, onderzoek op een precies framework toe spitsen). Of dat deze precies goed is (goldilocks zonde ;).

5. Peer assessment

De voorlaatste dag van de week doe je onderling peer assessment. Doe dit zowel mondeling als schriftelijk. Schriftelijk voor de aantoonbaarheid, en ook zodat de ander het ook rustig verwerken. Mondeling kun je details verder bespreken en vragen, en dit is goed om de feedback niet té comprehensive te maken.

Je kan het zo aanpakken:

  • Geef de ander toegang tot je prive repo en deze maakt een issue aan met hierin feedback.
  • Een pull request met suggesties voor verbetering stijl of fixen typo’s van concrete tekst.
  • En een beoordeling a.d.h.v. de beoordelingcriteria uit beoordelingsmodel op iSAS. Deze zijn in 3 hoofdcategorieën:
  • Onderwerp, diepgang, theorie/praktijk (KO)
  • Helderheid en doelgroepgerichtheid
  • Bronvermelding

Verwerk de gegeven feedback.

6. Schrijftips

Hieronder enkele schrijftips

  1. Gebruik zowel vrije tekst als meer gestructureerde elementen als tabellen en bullet lijsten
  2. Maak je werk reproduceerbaar en verifieerbaar door je werkwijze te beschrijven en bronnen te geven
  3. Geef je blogpost een logische structuur zodat deze leesbaar is

Hieronder verdere toelichting voor elk van deze punten. Lees ook eens deze blogpost van copyschool.nl (Driel, 2020). De tips 14 tot en met 19 van Jantien kun je negeren, want deze zijn meer voor weekbladen, maar de rest snijdt houdt; ook voor meer technische blogs.

6.1 Afwisseling tussen vrije tekst en gestructureerde elementen

Zorg dat je tekst structuur heeft. Door bijvoorbeeld het gebruik van bullet lijsten en/of tabellen. Maar zorg ook dat je blog niet ALLEEN uit bullet lijsten en tabellen bestaat (wat je veel studenten ziet doen in afstudeerverslagen). Dit doe je door ook vrije tekst toe te voegen. Geef elke bullet lijst een inleidende zin: wat voor soort items staan er in de lijst. Is het een en-en lijst? Of een of-of (e.g. beschrijft deze bv. alternatieve strategieen)? Al dit soort zaken zijn wellicht wel af te leiden door de lezer. Maar in een goed stuk hoeft de lezer weinig na te denken om het te begrijpen en heeft de schrijver juist extra veel nagedacht en/of moeite erin gestopt om de tekst duidelijk te maken. Zie verder ook sectie 'pyramid principle'.

Deze vrije tekst zelf structureer je wel via paragrafen. Paragrafen scheidt je van elkaar door een witregel. Als je enkel een harde enter plaatst kan het zijn dat de laatste zin van je paragraaf net zo lang is dat deze tot het eind van de regel loopt. Waardoor een lezer alsnog geen paragraaf overgang ziet. Bijvoorbeeld als een lezer op een mobiel device je artikel leest, terwijl je hem in desktop zelf hebt ingetikt.

6.2 Reproduceerbaarheid en gebruik bronnen (en conform APA)

Goed onderzoek is reproduceerbaar. Dat wil zeggen dat als iemand anders hetzelfde onderzoek doet dat deze tot dezelfde resultaten leidt. Alleen zulk onderzoek is betrouwbaar, en met de resultaten van zulk onderzoek kunnen anderen ook verder. En op de 'shoulders of giants' staan.

"If I had more time, I would have written you a shorter letter." - Blaise Pascal. (De kritische student onder jullie vraagt zich nu wellicht af waarom een Fransman een Engelse quote krijgt toegedicht. Een goede vraag...)

Binnen het HBO vinden we het belangrijk dat je een 'onderzoekende' mentaliteit hebt. Zeker in ICT leiden we namelijk op voor beroepen die wellicht nu nog helemaal niet bestaan. Wellicht wordt je een DevOps engineer, wat al wel een gangbare naam is, en tevens goedverdiendende rol ook nog. Maar wellicht verzint een bedrijf een meer of minder 'buzzwordy' titel voor hun vacture.

De internet variant van referenties zijn natuurlijk hyperlinks. En bij HBO ICT zijn 90+% van de bronnen internetbronnen. Voor je blog post moet je echter wel APA gebruiken. Deels om alvast te oefenen voor je afstuderen. Of omdat je begeleidend docent zelf ook echt streng is op precies APA gebruik. Regelmatig gebruiken studenten ook voetnoten bij het geven van APA referenties, maar dit is NIET het idee van APA en dus ook NIET conform APA. Dat wil zeggen: Voetnoten zijn niet verboden, maar voetnoten zijn voor voetnoten, dus een optionele toelichting op iets. Dit is iets anders dan bronvermelding, dit is bij de HAN niet optioneel, maar verplicht!

Een voor veel studenten onbekend issue is het verschil tussen een Literatuurlijst en een Bibliografie. En omdat Word als standaardtitel voor zo'n sectie 'Bibliografie' heeft, wordt dit veelal zo ingeleverd. Maar APA vereist een literatuurlijst, en dat is strikter dan een bibliografie, omdat in een literatuurlijst naar elke bron in deze lijst ook een referentie vanuit je tekst moet zijn.

Een bibliografie is een lijst van alle werken die je hebt gelezen tijdens het schrijven van een stuk. Maar hierbij hoef je niet per se te refereren naar de werken. Je zou bij wijze van spreken het kinderboek 'Pa Pinkelman en tante Pollewop' (Zonderland, D.) op kunnen nemen in je bibliografie, als dit boek je bijzonder veel ontspanning gaf tijdens een zware afstudeerperiode 😉. Maar omdat dit boek niet relevant past het NIET in een literatuurlijst.

Maar zonder gekheid, APA gaat dus uit van een 'Literatuurlijst', bij de HAN vaak 'Bronnen' genoemd!

6.3 Structureren van je blog post: section by feature (WIP)

Programmeertalen en natuurlijke talen zijn behoorlijk verschillend, maar er zijn ook overeenkomsten. Hierop gaan we hier niet verder in, maar wellicht een leuke oefening voor de lezer hiervan enkele voor zichzelf te noteren. Beiden hebben syntax én semantiek. Bij beiden moet ook een vertaalslag plaatsvinden; hetzij naar concepten in het menselijk brein, hetzij naar machine instructies die een processor kan uitvoeren bij het runnen van het programma.

Zo zijn ook code schrijven en tekst schrijven twee verschillende dingen, maar ook hier kun je overeenkomsten vinden. Een daarvan is dat structuur belangrijk is. Je programma deel je op functies. En in classes en/of modules zodra het enige schaal krijgt.

Hóe je het programma opdeelt is deel van het ontwerp, en zelfs van de (software) architectuur, want deze structuur verander je niet zomaar. Deze gaan dus horen bij de architectuur van je programma.

"Architecture is that part of design that is hard to change."

Een van de meest gestelde vragen van nieuwe programmeurs is: 'Ik heb het werkend, maar waar moet ik deze code neerzetten? In welke folder?'. Als je op dat moment geen duidelijk antwoord hebt, en maar wat gaat doen, creeer je een precedent. Dan gaat iedereen zijn eigen regels volgen. Om dit te voorkomen is het standaard antwoord vaak: de controller moet 'gewoon' bij de andere Controllers. Er is ook een mapje voor de Views en de Services.

Op deze oplossing is nogal wat op af te dingen, vooral als de applicatie over de jaren groeit en zeker als je 'Domain Driven Design' aanhangt (zoals in deze minor). Als je 'opeens' 10 of meer services in één folder hebt staan. Twee van deze services worden vanuit allerlei plekken gebruikt, vanuit de andere services en ook vanuit die ene repository, dat had wellicht netter gemoten, maar ja, het werkt wel. De andere 8 gebruik je slechts vanuit 'hun' controller, die in een heel ander mapje staat.

In een applicatie/repo/project heb je grofweg twee manieren om code te structureren:

  • package by type
  • package by feature

Dit idee van 'controllers bij controllers' noemt men Package by type . Alles bij zijn eigen type. Dit geeft wel een duidelijk antwoord. Waar plaats ik een service? In de services folder. En veel CLI's of IDE's geven je zelfs al een services folder en een controllers folder etc. om je extra productief te maken en zulke moeilijke vragen als 'waar moet deze klasse?' te voorkomen.

Maar zoals vaak komen de kosten van aan het begin minder nadenken later dubbel terug. De 'package by feature' optie vraagt wat meer denkwerk, want nu moet je zorgen dat de klasse of module een goede naam heeft. Namelijk die van zijn functionaliteit. Gaat deze code over 'rekeningen' (bills) of over voorraadbeheer (inventory)? En is het voorraadbeheer van de producten die je verkoopt (inventory/sales), of voorraadbeheer van spullen die je intern in bedrijf gebruikt en periodiek moet vernieuwen (/inventory/production). Of kun je folder 'inventory/sales' beter hernoemen naar stock om aan te sluiten bij woorden die ze in de business gebruiken? Nou dit neigt al naar de Ubiquitous language, zo'n beetje het belangrijkste pattern uit Domein Driven Design.

De package by feature' aanpak betekent in ieder geval dat de folderstructuur is niet meer standaard hetzelfde voor alle projecten, maar de folderstructuur geeft aan wat de applicatie doet. Als de stock folder 2x zoveel bestanden en/of subdirectories bevat als de inventory folder, geeft dit duidelijk aan dat hier meer logica in zit. En dat dit deel wellicht voor de core business in het bedrijf ook belangrijker is. En/of dat het complexer is om goed te automatiseren.

Het zal duidelijk zijn dat deze laatste te prefereren valt. Hoewel het vooral bedoeld is voor grotere projecten mag je hier zeker mee experimenteren ook in de wat kleinere projectjes op school. In het echte bedrijfsleven moet je zeker niet zomaar gaan switchen naar andere folder structuur, zonder eerst akkoord van management en/of afstemmen met mede developers. Er is ook nog de middenweg van package-by-type-by feature. Of package-by-feature-by-type. Dit mag je zelf bedenken wat dit is (/stock/controllers/ en stock/services). Maar als een folder maar een of een paar bestanden bevat, dan is een eigen subfolder NIET nodig.

Om de structuurmethode 'package by feature' te vertalen naar programmacode geldt dus ook dat je je blogpost opdeelt in subsecties. En dat je niet 1 sectie hebt waarin je voor alle deelvragen introduceert. Dan 1 sectie waarin je voor elke deelvraag de onderzoeksmethode berschrijft. En dan 1 sectie waarin je de bevindingen voor elke deelvraag opschrijft. En dan 1 sectie met de conclusie voor alle deelvragen. Je behandelt per al deze onderdelen binnen een sectie per deelvraag.

Wel heb je een introducerende sectie nodig die deze structuur beschrijft, en dus wel alle deelvragen en bijbehorende onderzoeksmethoden bv. kort opsomt. Gebruik verder per sectie ook niet de deelvraag zelf als sectietitel, maar gebruik een kortere variant hiervan. Kopjes is niet de bedoeling dat dit de volledige vraag is, of een volledige zin. Maar meer in een krantenkop stijl. Onder het kopje kun je de deelvraag wel geheel herhalen of parafraseren. NB: Een vraag eindigt altijd op een vraagteken. Dus doe dit ook. Bedenk dat in markdown default een kopje ook niet mag eindigen met een leesteken volgens de mdlint regel. Dit is omdat "Headings are not meant to be full sentences".

Verder lezen:

6.4 Pyramid principle

Als je je schrijven echt naar een hoger niveau wilt tillen verdiep je dan eens in de 'Pyramid Principle' van Barbara Minto. Je kunt haar originele boek lezen of wat samenvattende blogposts, maar dat is wellicht wat zwaar. De essentie van haar verhaal is dat je vaak je 'schrijfsel' moet 'omdraaien' t.o.v. hoe je het origineel opschreef. Zie illustratieve plaatje/comic van sketchplanations in figuur 1 (Sketchplanations, z.d.)

Sketchplanations: The pyramid principle in 1 plaatje

Figuur 1: The pyramid principle in 1 plaatje (Bron: sketchplanations.com)

Dat wil dus zeggen dat je je document BEGINT met de eindconclusie die je uiteindelijk bereikt hebt. Of het eindresultaat.

Bijvoorbeeld: Ik heb een kleine webapplicatie gemaakt met een 3-tier architectuur, met front-end en database in een aparte container, en de back-end in het midden opgedeeld in 2 microservices elk draaiend in hun eigen container.

Mensen hebben namelijk standaard de neiging om verhalen chronologisch op te schrijven. Namelijk, eerst deed ik dit, en toen deed ik dat, zodat uiteindelijk... Of een argumentatie: 'omdat A het geval is, en ook B, en natuurlijk niet C1 en C2 — die je samen zou kunnen vatten als C — kom ik tot de conclusie dat D'. Dit is een vereenvoudigd voorbeeld - vandaar de variabelen - maar in werkelijkheid zou deze structuur dus jouw hele blogpost van 2 of meer A4's kunnen zijn. In plaats van de ene zin die het voorbeeld nu is. Of zelfs een heel afstudeerverslag. In de 'Minto' methode zou je dit omdraaien naar 'Ik vind dat D. Dit komt omdat A, B en C, die ik in sectie 2.3, 2.4 en 2.5 verder uitwerk.

Je moet dit niet alleen op de schaal van je hele document doen. Maar ook elk subhoofdstuk intern weer zo opdelen. Want je kent dit wellicht al in de vorm van een 'managementsamenvatting' die je vooraan een verslag zet. Of gewoon een samenvatting, want het management is lang niet altijd je doelgroep. Maar juist op het middelste niveau maakt dit je verslag leesbaarder en toegankelijker. Heel veel studenten stouen hun verslag vol met tabellen met Requirements, of bullet lijsten met user stories. Geef naast de leeswijzer in hoofstuk 1 'Inleiding' die de rest van het document beschrijft, ook elk hoofdstuk zijn eigen leeswijzer. In tegenstelling tot de leeswijzer, die aan het eind van de inleiding staat, staan deze interne leeswijzers juist direct aan het begin van hun hoofdstuk. Gebruik verder ook NIET het kopje 'Leeswijzer' voor deze sectie. En zelfs geen subkopje '3.1 Inleiding'. Gebruik voor sectie kopjes zoveel mogelijk inhoudelijke termen uit je applicatie, die gaan over WAT je beschrijft. En niet HOE je het beschrijft. Dit laatste kun je toelichten in tekst zelf, of wijst zichzelf.

Dus NIET sectie of hoofdstuk '4. MoSCow' (HOE je de prioritering aangeeft), maar '4. Prioriteiten' met daarin 1e paragraaf: "Tabel 4.1 hieronder geeft de prioriteitsindeling van de user stories uit H3 volgens de MoSCoW methode (Mulder, P., 2017), zoals besproken met de product owner."

Bronnen

Last change: 2025-01-13