TechWiki

Deze repository bevat een technische wiki en de code van de experimenten. De wiki staat in Markdown. Elke pagina volgt één stel schrijfregels.

De schrijfregels volgen de principes van ASD-STE100, de specificatie voor Simplified Technical English (STE). De repository claimt geen naleving van die specificatie.

Nederlands is de hoofdtaal. Engels is de tweede taal. Zie README.en.md voor de Engelse tekst.

Lezers

Twee groepen lezers gebruiken deze repository.

• Studenten lezen de code en de wiki om een systeem te leren.
• Software-agents lezen de wiki om een taak af te ronden.

Beide groepen lezen woord voor woord. Beide groepen verliezen tijd bij een zin met twee betekenissen. De regels halen die dubbelheid weg.

Indeling

Pad	Inhoud
wiki/index.md	De startpagina van de wiki.
wiki/conventies/	De schrijfregels, de codestijl en de werkwijze.
wiki/gidsen/	De taken van een auteur en van een programmeur.
wiki/onderwerpen/	Het project, de platformen en het bouwen.
wiki/sjablonen/	Eén sjabloon per paginatype.
tools/check_docs.py	Het script dat een pagina tegen de regels controleert.
experiments/	De experimenten met code.

Start hier

1. Open wiki/index.md.
2. Lees Schrijfregels.
3. Lees Woordenlijst.
4. Lees Pagina toevoegen.

Een programmeur leest daarnaast Projectcontext en C-codestijl.

De schrijfregels in het kort

• Eén woord, één betekenis. Gebruik één werkwoord voor één handeling.
• Eén woordsoort per woord. Gebruik een naamwoord niet als werkwoord.
• Actieve vorm. Noem de handelende partij voor het werkwoord.
• Alleen enkelvoudige tijden. Gebruik geen voltooide tijd.
• Eén instructie per zin.
• 20 woorden per instructie. 25 woorden per beschrijvende zin.
• 3 woorden per groep zelfstandige naamwoorden.
• Geen weglating. Houd het onderwerp, het werkwoord en het lidwoord.
• 6 zinnen per alinea. Eén onderwerp per alinea.
• Een lijst bij 3 stappen of meer.
• Een uitleg bij elke vakterm op het eerste gebruik.

De regels gelden voor elk bestand in deze repository. De regels gelden voor een README.md, voor een commentaarregel, voor een docstring, voor een logregel en voor een instructie aan een agent.

De wiki controleren

make check

Het commando voert tools/check_docs.py uit. Het script vraagt Python 3.10 of een latere versie. Het script gebruikt alleen de standaardbibliotheek.

Het script schrijft één regel per bevinding. Een fout stopt de samenvoeging. Een waarschuwing vraagt een blik van een mens.

make check-strict

Het doel check-strict behandelt een waarschuwing als een fout.

Meewerken

Lees CONTRIBUTING.md voor je eerste verandering. Een agent leest CLAUDE.md.

Licentie

Deze repository gebruikt de licentie in het bestand LICENSE.