Suggesties template / docs

[PHaasnoot]

Ervaringen met gebruik template:

-> readme geeft aan dat controles worden gedaan,
welke precies is interessant voor nieuwe gebruikers

-> workflow actions geven foutmeldingen
waarschijnlijk in dit geval door kopie in private repo
hiervoor is misschien ook een toelichting nodig voor nieuwe gebruikers (dwz wf actions alleen werken in public repos)

-> als config.js een struktuur fout heeft, blijft het scherm leeg zonder foutmeldingen, mogelijk zijn hier voor nieuwe gebruikers nog
aanvullende controles mogelijk

-> titel van document wordt nu in index.html gezet conform respec opzet, een future extension is mogelijk nog een optie om
alles in MD of config te kunnen specificeren (dwz om het voor een nieuwe gebruiker gemakkelijker te maken)

-> respec werkt met 1 md file per hoofdstuk, soms is het handig om in 1 MD meerdere h-stukken te kunnen specificeren

[RickdeBruijn]

in f618805 staat een beschrijving van de checks in de readme

[RickdeBruijn]

https://github.com/Logius-standaarden/ReSpec-template/pull/22/files maakt de titel aanpasbaar via de config file

[RickdeBruijn]

Er word ervanuit gegaan dat er enige technische kennis aanwezig is (zie de readme), dit en het feit dat als een van de config files geen correct object is het hele document niet laad. Zal er voor zorgen dat een fout maken in de config file geen groot probleem zal zijn. Als er missende configuratie opties zijn zal de missingConfigWarner dat aangeven met een link naar de wiki van die config variabel

[sanderke]

Meer dan één H1 per document gaat ook tegen de Markdown best practices.

[RickdeBruijn]

Heb het probleem doorgenomen met Peter, het probleem is niet h1.
Het probleem is dat respec de heading van de markdown deels lijkt te negeren. aan de hand van de volgorde van headers word het headernummer veranderd.

ch01.md =>

## Niet-normatieve deel
# h2
### h3
## h4
# h5

resulteerd in:

het is uiteraard een rare manier van header volgorde maar het laat zien dat respec zelf de header groote verandert aan de hand van volgorde in het document.