User Tools

Site Tools


resources:structuur

This is an old revision of the document!


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