Status: Deprecated | Owner: @roof | Updated: 2026-06-11
⚠️ ARCHIVED — ADRs cover PIC product and code decisions only; documentation-process decisions are out of ADR scope. The decision itself still stands: the wiki is the single documentation source and the code repo keeps only
README.md.
ADR – 004 The Wiki Is the Single Documentation Source
Context
As PIC grew, documentation accumulated in multiple places:
QUICKSTART.md— install guide in the repo rootPersonal Internet Cell – Project Wiki.md— a monolithic ~5,000-word markdown file in the repoapi/API_DOCUMENTATION.md— a 1,285-line endpoint reference that still described localhost-only auth and DHCPdocs/service-developer-guide.md— the service manifest referencewebui/README.md— frontend notes for developers
These sources drifted rapidly from reality. Because they lived in the git repo, updating them required a code review and merge. Docs for last month's code frequently shipped alongside this month's features. Users reading the README on the repository landing page followed instructions that no longer applied.
The Gitea wiki (this wiki) also existed but was treated as optional — some topics appeared here and also in the repo, with the two copies diverging.
Options Considered
Option A — Docs-as-code in the repository
Keep all documentation in the repo, enforce updates via CI lint checks, require docs changes in the same PR as code changes.
Rejected because: this tightens the coupling without solving the drift problem. A CI lint check can verify that documentation exists but cannot verify that it is accurate. Requiring docs PRs for every code change slows down contributors without improving quality. The monolithic markdown file becomes a merge-conflict magnet.
Option B — External hosted documentation (Docusaurus, Read the Docs, etc.)
Move all documentation to a dedicated docs site with versioning.
Rejected because: it introduces another infrastructure dependency for a project whose primary goal is minimising dependencies. It also creates a three-way split (repo, wiki, docs site) rather than resolving the two-way split that already exists.
Option C — Gitea wiki as the single source (chosen)
Move all guides, references, and decisions into this Gitea wiki. Strip the repository down to README.md only (project overview and a pointer to the wiki). Content pinned to a code version (API reference, sample configs, build scripts, CHANGELOG) is linked to the repo at a tag/commit permalink rather than pasted into a wiki page.
The wiki is a git repository (pic.wiki.git) with its own commit history, accessible directly without going through a code review process, and editable by anyone with wiki write access. This lowers the friction for keeping docs current.
Decision
This Gitea wiki is the single authoritative source for all explanations, guides, decisions, and troubleshooting. The repository's only documentation file is README.md (overview + pointer to the wiki). All other markdown documentation files in the repo have been deleted.
The rule is: when you merge a code change that changes user-visible behaviour, admin procedures, or the developer API, you update the wiki in the same session. The wiki must not drift from the code.
Consequences
- One place to update. Contributors know where to look and where to write. There is no ambiguity about which copy is authoritative.
- The wiki must be updated in the same change as the code. This is a discipline constraint, not a technical enforcement. The pre-commit hook in the repo does not check the wiki. Reviewers are responsible for flagging wiki-missing PRs.
- Version-sensitive content is linked, not pasted. API reference pages, manifest examples, and install scripts in the wiki link to the repository at a specific commit or tag. Pasting them into a wiki page would re-introduce drift. The
Applies to: main (YYYY-MM)header on version-dependent pages signals when a page was last verified against the code. - The
Archive –prefix marks deprecated pages. Old pages are never deleted; they are renamed withArchive –and moved out of the sidebar's main sections. This preserves historical context without polluting current navigation. - The wiki structure uses audience grades (User / Admin / Dev / ADR / Meta / Archive). This prevents documentation for one audience from being buried in material aimed at another, which was a recurring problem with the monolithic markdown file.
See also ADR – 003 All Optional Functionality Ships as Store Services for the related decision that removed service documentation from the repo.
Personal Internet Cell
New here?
Users
User – Connect to the VPN User – Use Your Services User – Troubleshooting
Admins
Admin – Overview Admin – Install and First Run Admin – Configure Domains and TLS Admin – Manage Services Admin – Configure Connectivity Admin – Manage Peers Admin – Back Up and Restore Admin – Logging and Audit Admin – Monitor and Troubleshoot
Developers
Dev – Overview Dev – Architecture Dev – Build a Store Service Dev – Service Manifest Reference Dev – API Reference Dev – Testing Dev – Install Internals
Decisions (ADRs)
ADR – 001 Store Images Are Signed and Verified by Cells ADR – 002 Named Connection Instances for Connectivity ADR – 003 All Optional Functionality Ships as Store Services
Meta
Meta – Glossary Meta – Template Runbook Meta – Template ADR
Archive
Archive – User Guide Archive – ADR 004 The Wiki Is the Single Documentation Source