====== 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. * **[[resources:metadata:tags:status|Status]]**: {{tag>vastgesteld}} ===== 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 [[homelab:standaarden:netwerk:ip-plan|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 | | **Les** | Hoe iets werkt of hoe je iets aanpakt, rond één punt | Regels, het waarom en de huidige staat: daarvoor verwijst hij naar de standaard, het besluit of de 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 [[resources:metadata:tags:thema|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 [[resources:metadata:tags:status|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. * **Les**: Reden, Gebruik bij, Geldt voor en Gecontroleerd ingevuld; stappen doorlopen (of met reden gemarkeerd als niet doorlopen); verwijst naar de feiten in plaats van ze te herhalen. ===== 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". ===== Lessen ===== * Een les legt uit hoe iets werkt of hoe je iets aanpakt, rond één punt. Hij komt in de wiki op verzoek van de eigenaar, niet automatisch na elke chat. * Een les beschrijft een standaardwijziging (naar ITIL): terugkerend, laag risico, vooraf doordacht. Hij is de moeite waard als minstens één geldt: de actie komt regelmatig terug, het uitvoeren is niet vanzelfsprekend, of een leermoment moet worden geborgd voor een situatie die zich kan herhalen. Vervalt de reden, dan gaat de les naar ''archief''. * Opbouw: Wat, Doel, Reden, Gebruik bij, Geldt voor, Gecontroleerd, Betreft, status en thematags, daarna Uitgangspunt, Stappen of uitleg, Controle en Bronnen. * Een les herhaalt geen feiten (poorten, profielen, instellingen). Die staan in de standaard, het besluit of de service waarnaar de les verwijst. * **Gecontroleerd** noemt de datum en hoe: de stappen doorlopen, of alleen tegen de wiki gelezen. Een stap die niet is doorlopen, zegt dat. * Een les blijft actueel via de thematags: de lessen staan in de paginalijst van de tag. Wijzig je iets waarvoor een tag geldt, loop dan ook de lessen met die tag na en werk //Gecontroleerd// bij. Past een les niet meer, zet hem dan op ''verouderd''.