docs: create Documentation_Standards

Documentation_Standards.md

@@ -0,0 +1,276 @@
+---
+title: Netgrimoire Documentation
+description: How to create and use Netgrimoire Docs
+published: true
+date: 2026-02-03T02:54:56.444Z
+tags: 
+editor: markdown
+dateCreated: 2026-02-03T02:54:56.444Z
+---
+
+# Homelab Documentation Structure & Diagram Standards
+
+This document describes the **official documentation structure** for the homelab Wiki.js instance, including:
+- Folder and page layout
+- Naming conventions
+- How Git fits into the workflow
+- How to use draw.io (diagrams.net) for diagrams
+- How to ensure documentation is accessible when the lab is down
+
+This page is intended to be a **reference and enforcement guide**.
+
+---
+
+## Core Principles
+
+1. **Wiki.js is the editor, Git is the source of truth**
+2. **All documentation must be readable without Wiki.js**
+3. **Diagrams must be viewable without draw.io**
+4. **Folder structure must be predictable and consistent**
+5. **Emergency documentation must not depend on the lab being up**
+
+---
+
+## Repository Overview
+
+All documentation lives in a single Git repository.
+
+Wiki.js writes Markdown files into this repository automatically.  
+The repository can be cloned to a laptop or other device for **offline access**.
+
+Example:
+```bash
+git clone ssh://git@forgejo.example.com/homelab/docs.git
+```
+
+---
+
+## Top-Level Folder Structure
+```
+homelab-docs/
+├── README.md
+├── emergency/
+├── infrastructure/
+├── storage/
+├── services/
+├── runbooks/
+├── diagrams/
+└── assets/
+```
+
+### Folder Purpose
+
+| Folder | Purpose |
+|--------|---------|
+| README.md | Entry point when the lab is down |
+| emergency/ | Recovery procedures and break-glass docs |
+| infrastructure/ | Core systems (identity, backups, networking) |
+| storage/ | Storage platforms and layouts |
+| services/ | Application-specific documentation |
+| runbooks/ | Step-by-step operational procedures |
+| diagrams/ | All draw.io diagrams and exports |
+| assets/ | Images or files used by documentation |
+
+---
+
+## Storage Documentation Structure
+```
+storage/
+└── core/
+    ├── zfs.md
+    ├── local-drives.md
+    ├── nas.md
+    └── btrfs.md
+```
+
+**Guidelines:**
+- Each storage technology gets its own page
+- Pages describe architecture, layout, and operational notes
+- Backup and snapshot policies belong elsewhere
+
+---
+
+## Infrastructure Documentation Structure
+```
+infrastructure/
+└── backups/
+    ├── zfs-snapshots.md
+    └── application-backups.md
+```
+
+**Guidelines:**
+- Infrastructure describes cross-cutting systems
+- Anything used by multiple hosts or services belongs here
+- Backup strategies are infrastructure, not storage
+
+---
+
+## Services Documentation Structure
+```
+services/
+└── mailcow.md
+```
+
+**Guidelines:**
+- One page per service
+- Page should include:
+  - Purpose
+  - Architecture
+  - Volumes
+  - Backup considerations
+  - Recovery notes
+
+---
+
+## Emergency Documentation
+```
+emergency/
+├── bring-up-order.md
+├── swarm-recovery.md
+├── zfs-import.md
+├── network-restore.md
+└── identity-break-glass.md
+```
+
+**Rules:**
+
+Emergency docs must be:
+- Text-first
+- Copy/paste friendly
+- Free of dependencies
+
+These pages should be readable directly from Git.
+
+---
+
+## Naming Conventions (Mandatory)
+
+**Folders:**
+- Lowercase
+- No spaces
+- Example: `infrastructure/backups`
+
+**Page filenames:**
+- Lowercase
+- Hyphen-separated
+- Example: `zfs-snapshots.md`
+
+**Page titles:**
+- Human readable
+- Proper case
+- Example: `# ZFS Snapshots`
+
+---
+
+## draw.io (diagrams.net) Usage
+
+draw.io is used **only to create diagrams**, never as the sole storage location.
+
+### Diagram Storage Layout
+```
+diagrams/
+├── network/
+│   ├── core.drawio
+│   ├── core.png
+│   └── core.svg
+├── docker/
+│   ├── swarm-architecture.drawio
+│   └── swarm-architecture.png
+└── storage/
+    ├── zfs-layout.drawio
+    └── zfs-layout.png
+```
+
+### File Types
+
+| File | Purpose |
+|------|---------|
+| .drawio | Editable source |
+| .png | Offline viewing |
+| .svg | Zoomable / high quality (optional) |
+
+**Every diagram MUST have a PNG export.**
+
+---
+
+## Adding a Diagram (Required Workflow)
+
+1. Create or edit the diagram in draw.io
+2. Save the `.drawio` file into `diagrams/<category>/`
+3. Export a `.png` (and optional `.svg`)
+4. Commit all files to Git
+
+If a diagram cannot be viewed without draw.io running, it is **not complete**.
+
+---
+
+## Embedding Diagrams in Wiki.js Pages
+
+Always embed PNG or SVG, never live editors.
+
+Example:
+```markdown
+![Core Network Diagram](../../diagrams/network/core.png)
+
+_Source file: core.drawio_
+```
+
+This ensures:
+- Fast rendering
+- Offline viewing
+- No service dependency
+
+---
+
+## Git Workflow Expectations
+
+**Authoring:**
+- All pages are created and edited in Wiki.js
+- Wiki.js commits changes automatically
+
+**Offline Access:**
+- Documentation is read directly from the Git clone
+- Markdown and images must be sufficient without Wiki.js
+
+**What Not To Do:**
+- Do not create wiki pages directly in Git
+- Do not rename paths outside Wiki.js
+- Do not store diagrams only inside draw.io
+
+---
+
+## Lab-Down Access Model
+
+When the lab is unavailable:
+
+1. Open the local Git clone
+2. Read `README.md`
+3. Navigate to `emergency/`
+4. View diagrams via `.png` files
+5. Execute recovery steps
+
+**No services are required.**
+
+---
+
+## README.md (Recommended Content)
+
+The root `README.md` should contain:
+- Purpose of the documentation
+- Where to start during an outage
+- Link list to emergency procedures
+- High-level architecture notes
+
+---
+
+## Final Notes
+
+This structure is designed to:
+- Scale cleanly
+- Survive outages
+- Remain readable for years
+- Support automation and GitOps workflows
+
+**If documentation cannot be read when the lab is down, it is incomplete.**
+
+This structure makes that impossible.