Standaarden: README inhoud en aanvullende md's

[CorneeldH]

Wat wel en niet in README, wat in aanvullende md en hoe stylen we dit?

Obv gesprekken afgelopen dagen roep ik even paar dingen:

• Nederlandse taal
• Ik vind 1CijferHO readme overall mooi
• Ik vond gifje heel leuk, dat bovenin en het (het liefst) bij meer repo's? Uiteraard hoeven we het niet bij iedere commit te updaten, maar het geeft toch een beetje gevoel erbij. Of anders een screenshot.
• emoji bij headers? geeft iets meer smoel
• Willen een soort max lengte?
• in deze README.md alleen iets over relevantie + instructies over 'runnen' in, of ook iets over structuur repo?

Aanvullende md's

• CLAUDE.md, bij actieve repo's erbij?
• een meer technische md met uitleg? Hoeveel toegevoegde waarde heeft dit? En waar zit dit dan? in /docs? Ik wil het liefst de main folder zo clean mogelijk houden. En hoe heet deze md? Een standaard naam is wel handig (en dan kan de CLAUDE.md daar ook naar verwijzen). architecture.md? tech.md?

Roept u maar! : @cedanl/admin

Als we hierover uit zijn dan kunnen we dit in standaard CLAUDE.md / skill zetten.

[tcbakker]

Hoi Corneel, Is dit ook voor mij bestemd? Misschien sta ik nog in een team. Kan je me daaruit halen? Vriendelijke groet, Theo Dr. Theo Bakker Lector Learning Technology & Analytics 06 25 63 71 72 | Berichten via Teams of Signal ***@***.******@***.***> | ORCID 0000-0002-0735-9636<https://orcid.org/0000-0002-0735-9636> https://www.linkedin.com/in/theobakker/ | https://hapax-analytics.nl/ Neem voor afspraken contact op met mijn management-assistente, Monique van der Made, ***@***.******@***.***>, 06 - 2835 2901. Werkdagen: Ma, Wo-Vr: HHs, Di: VU De Haagse Hogeschool Center of Expertise Global & Inclusive Learning / Faculteit IT & Design Johanna Westerdijkplein 75, 2521 EN Den Haag dehaagsehogeschool.nl<http://www.dehaagsehogeschool.nl/> Van: Corneel ***@***.***> Datum: vrijdag, 6 februari 2026 om 17:22 Aan: cedanl/centre_documentation ***@***.***> CC: Theo Bakker ***@***.***>, Team mention ***@***.***> Onderwerp: [CEDA (Centre for Educational Data Analytics)] Standaarden: README inhoud en aanvullende md's (Discussion #6) Wat wel en niet in README, wat in aanvullende md en hoe stylen we dit? Obv gesprekken afgelopen dagen roep ik even paar dingen: * Nederlandse taal * Ik vind 1CijferHO readme overall mooi * Ik vond gifje heel leuk, dat bovenin en het (het liefst) bij meer repo's? Uiteraard hoeven we het niet bij iedere commit te updaten, maar het geeft toch een beetje gevoel erbij. Of anders een screenshot. * emoji bij headers? geeft iets meer smoel * Willen een soort max lengte? * in deze README.md alleen iets over relevantie + instructies over 'runnen' in, of ook iets over structuur repo? Aanvullende md's * CLAUDE.md, bij actieve repo's erbij? * een meer technische md met uitleg? Hoeveel toegevoegde waarde heeft dit? En waar zit dit dan? in /docs? Ik wil het liefst de main folder zo clean mogelijk houden. En hoe heet deze md? Een standaard naam is wel handig (en dan kan de CLAUDE.md daar ook naar verwijzen). architecture.md? tech.md? Roept u maar! : @cedanl/admin<https://github.com/orgs/cedanl/teams/admin> Als we hierover uit zijn dan kunnen we dit in standaard CLAUDE.md / skill zetten. — Reply to this email directly, view it on GitHub<#6>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ABWNGHGXACX5JZ222BJLPGD4KS5VZAVCNFSM6AAAAACUH4ARGWVHI2DSMVQWIX3LMV43ERDJONRXK43TNFXW4OZZGQZTQMRUGM>. You are receiving this because you are on a team that was mentioned.

[CorneeldH]

Je bent als gebruiker en ervaringsdeskundige van harte uitgenodigd mee te denken, Theo ;-)

Ik haal je uit de admin lijst

[Tomeriko96]

Hier even de link naar de 1cijferho repo https://github.com/cedanl/1cijferho

Ik vond gifje heel leuk, dat bovenin en het (het liefst) bij meer repo's? Uiteraard hoeven we het niet bij iedere commit te updaten, maar het geeft toch een beetje gevoel erbij. Of anders een screenshot.

Normaal gesproken ben ik het ermee eens dat een gifje bovenaan hoort. In dit geval vind ik dat de huidige video niet goed laat zien wat de repo precies doet. Het belangrijkste doel van de README is dat een gebruiker direct snapt waar de repo voor dient.

[StevenRamondt]

Eens. Verder natuurlijk wel proberen (als logisch is) zo vaak mogelijk boven aan en gif liever dan screentshot. Maar dat kan mogelijk ook niet altijd.

[Tomeriko96]

emoji bij headers? geeft iets meer smoel

Daar ben ik persoonlijk wat minder fan van. Een paar emoji’s in de README kan prima, maar bij elke header wordt het wat druk.

[StevenRamondt]

Ik ook niet. In onze sector is neutraliteit, rust en consistentie belangrijk. Om al onze grotere doelen te behalen moeten we ook een bepaalde profesionaliteit uitstralen. Spaarzaam en liever niet.

[Tomeriko96]

in deze README.md alleen iets over relevantie + instructies over 'runnen' in, of ook iets over structuur repo?

Daar twijfel ik nog over, vooral gezien de behoefte van ons publiek.

[SKvdV]

Ik denk vooral relevantie en instructie om te kunnen runnen.

Projectstructuur is meer voor de ontwikkelaars / techneuten.

[StevenRamondt]

Publiek is in veel gevallen nog duaal. Dus eindgebruikers en datamensen. We doen nu net alsof we met bijvoorbeeld 1cijferho bestand een volledige pipeline kunnen opzetten en alles kunenn verwerken naar eindgebruiker. Daar zijn we echt nog lang niet en dat is gewoonweg voor de meeste dataprojecten niet voldoende data.

Ik ben voorstander van een minimale README.md maar dan wel met meer links naar .md files. Technische , structuur, claude en mogelijk meer. Misschien moet er dan een extra folder in de main of is er op een andere manier ' vervuiling', maar anders is het niet bruikbaar voor practische projecten. Ik heb geen keyusers in MBO anders meer.

"Projectstructuur is meer voor de ontwikkelaars / techneuten." Dit roept bij mij ook vragen op over of we willen dat instellingen ook aan de slag gaan of dat we alles zelf gaan doen. Als we alles zelf gaan doen dan kan je mijn comment negeren. Maar dan moet de prioriteit erg gaan veranderen.

[CorneeldH]

Lijkt me goed om te verwijzen. Je wilt niet een 'wall of text', maar ook niet dat dingen verborgen zijn. Mbt agentic workflows zijn verwijzingen ook heel interessant, het bespaart tokens en kwaliteit van context window om niet altijd alle tekst er direct in te pompen.

[CorneeldH]

Dank voor de input iedereen!

Zie de nieuwe standaarden: https://github.com/cedanl/.github/tree/main/standards, met daarin iets over readme. Nieuwe ideeën en updates kunnen in de repo worden besproken via issues en pull requests.