From d85b984c71ed18ad6188d35e268878126e5cf913 Mon Sep 17 00:00:00 2001 From: Administrator Date: Tue, 3 Feb 2026 02:55:08 +0000 Subject: [PATCH] docs: create Documentation_Standards --- Documentation_Standards.md | 276 +++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 Documentation_Standards.md diff --git a/Documentation_Standards.md b/Documentation_Standards.md new file mode 100644 index 0000000..e1f96cb --- /dev/null +++ b/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//` +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. \ No newline at end of file