resources:structuur
This is an old revision of the document!
Table of Contents
Documentatie-afspraken
- Wat: de afspraken voor het opzetten en bijhouden van de homelab-documentatie in deze wiki.
- Doel: elke pagina volgt dezelfde opzet, zodat configuraties en de afwegingen erachter terug te vinden zijn zonder overdocumentatie.
Uitgangspunten
- De wiki beschrijft de eindstaat. Geen changelog, voortgang of open punten: de revisies van DokuWiki volstaan.
- Per project één afsluitstap: de besluitpagina en de service- of devicepagina bijwerken.
- Een feit staat op één plek. Andere pagina's verwijzen er met een link naar.
- Configuratie die alleen in de apps zit (Home Assistant, OpenWrt, DSM): alleen afwijkingen van de default, met reden. Geen volledige kopie en geen verwijzing naar exports of backups.
- Gebruikers: de wiki is er voor één gebruiker. Doel van het gebruik: herstel na een storing, raadplegen voor een aanpassing (kan ik instelling A wijzigen?), oppakken na een pauze en context geven aan Claude.
- Uitzondering op de eindstaat-regel: het ip-plan bevat VLAN 5 (servers) als gepland, met overwegingen, zodat het later weer opgepakt kan worden.
Soorten pagina's
| Soort | Beschrijft | Beschrijft niet |
|---|---|---|
| Besluit | Het waarom en de afgewezen alternatieven | De huidige staat en how-to's |
| Service | Huidige staat, afwijkende instellingen met reden, beheer en problemen | Beleid en afwegingen (staan in het besluit) |
| Device | Hardware, plaatsing, beheer | Services die erop draaien (komen via backlinks) |
| Standaard | Baseline voor de inrichting van het homelab: netwerk, backups, namen | Specifieke configuraties van een device of service |
Opmaak
- Elke pagina begint met een korte Wat-regel, gevolgd door Doel.
- Links zijn altijd beschrijvend: alleen het deel dat de bestemming beschrijft is de link, bijvoorbeeld
Zie [[https://voorbeeld.nl|de productspecificaties]]. Geen kale URL's in lopende tekst. - Een servicepagina heeft een link naar de GUI van de service, als die er is.
- Een besluit vermeldt de geraadpleegde externe bronnen (beschrijvend gelinkt), waar relevant.
- Plugin-syntax (catlist, backlinks, topic, tag en
/* */) staat aan de randen: start-pagina's, templates en de sectie Relaties. Niet midden in de tekst. Mermaid-diagrammen mogen overal.
Namen van pagina's
- Namespaces en paginanamen zijn Nederlands en in kleine letters.
- Een streep na het nummer en een streep binnen een eigennaam of samenstelling:
tp-link,arr-stack,ip-plan,xp-8700. - Een underscore voor de spatie tussen woorden:
26.009-updatebeleid_containers_wud. - Hernoemen of verplaatsen gaat via de movepage-plugin, zodat links meeverhuizen.
Tags
- Elke pagina heeft precies één statustag (zie hieronder) en nul of meer thematags. Overige tags zijn niet toegestaan.
- Thematags zijn de ingang voor wijzigingen: wijzig je bijvoorbeeld de internetsnelheid, dan controleer je alle pagina's met de tag
bandbreedte. - Elke thematag heeft een eigen pagina met uitleg, de sectie Bij wijziging (wat controleren) en een automatische paginalijst. Het overzicht staat op de thematags.
- Tagnamen: kleine letters, enkelvoud, koppeltekens in plaats van spaties.
Wachtwoorden en tokens
- Staan in LastPass, in een item met de naam van de service.
- Een pagina vermeldt het alleen als het item anders heet.
- Nooit secrets in de wiki.
Status en Definition of Done
Statussen (zie de statustags): concept, vastgesteld, verouderd en archief. Een pagina is vastgesteld als hij voldoet aan de Definition of Done en gecontroleerd is. Tot die tijd blijft hij concept.
Alle soorten
- Wat- en Doel-regel
- Geen secrets
- Links zijn beschrijvend
- Een status- en eventuele thematags
- Elk blok is gevuld of verwijderd (geen lege blokken)
- Feiten zijn gecontroleerd tegen de bron (compose-bestand, GUI of eigenaar)
Per soort, daarbovenop
- Service: link naar het device, link naar de GUI (indien aanwezig), afwijkende instellingen met reden, verwijzing naar de standaard voor backups en netwerk.
- Device: hardware en OS, locatie, kritisch voor, toegang voor beheer, netwerk met verwijzing naar het ip-plan.
- Besluit: context, overwogen opties inclusief afgewezen, besluit, gevolgen, betrokken pagina's, bronnen (indien relevant).
- Standaard: regel, toepassingsgebied, voorbeeld.
Besluiten
- Opbouw: Wat, context, opties (inclusief afgewezen), besluit, gevolgen en bronnen. Evaluatie en “wanneer heroverwegen” zijn optioneel.
- De betrokken pagina's staan op één regel: “Betreft: …”.
- Een besluit heeft geen status “voorgesteld”.
resources/structuur.1792501537.txt.gz · Last modified: by miels
