Where documentation belongs
Anything that must match a specific commit, branch, or release goes into the package repository; guidance for users and administrators goes into the public wiki.
Scope and authority
The White Knight Labs, which operates this wiki, adopted this rule. It has been in force since September 26, 2026, and applies to:
- the company's own DokuWiki packages in the DokuWiki-Plugins project – 29 packages whose names start with
wk - the repositories of these packages
- their wiki pages under
<lang>:wiki:dwe:<package>in all three languages - the contributor pages under
<lang>:wiki:help:projects
This page is the canonical statement of the rule. Short summaries elsewhere, such as the house documentation skill or a package's CONTRIBUTING file, point here. Where they differ, this page takes precedence.
Purpose
Each piece of information lives in exactly one place, so that no second copy can contradict it.
An inventory taken before this rule came into force shows what happens otherwise. The 29 packages maintained their user documentation in two places: as English Markdown in the repository and as wiki pages in up to five languages. The inventory found 145 pairs of documents on the same topic, almost all of which overlapped only in part, and 202 statements that did not match the code. For example, the reference page of a menu plugin named only two of its five settings, a README documented a syntax that the plugin does not recognize, and defaults stated in the wiki contradicted the code.
One README was copied into the wiki, and within 10 weeks three different versions existed: the wiki copy, the file in the repository, and the deployed file.
Audience
This rule is for everyone who writes or reviews documentation for the packages:
- authors of wiki pages
- contributors to the packages
- maintainers
- reviewers of changes
Core principles
- Ask one question. Must this information stay in sync with a specific commit, branch, or release? If so, it goes into the package repository. If not, and it answers a question from a user or an administrator, it goes into the public wiki.
- The reference lives with the code. The public interface, syntax, configuration keys with their type and default, and contracts live in the repository, in
docs/api-reference.md, in English. A package'sreferencewiki page is a signpost: it says what the reference contains and links to the project's repository screen, where you can read the file on any branch or at any commit. The wiki neither copies nor embeds the file. - Never copy between repository and wiki. Link instead, or generate the wiki content from the repository, the way the component matrix is generated from
wkcomponent.json. A copy that has to be kept in sync by hand drifts; the figures under Purpose show how far. - Documentation-first is a way of working, not an order of precedence. You can write a specification before the code. Once the code is released, the code is authoritative: correct the text to match what the code does, and remove the marker that labels it as a specification.
- Each place has its own language. Markdown in the repository is English only. Wiki pages exist in German, English, and Slovenian; each version is written in its own language from the verified facts, never translated from another version, and reviewed by an editor for that language. Work items, commit messages, and pull request descriptions may be in German. File and namespace names are always English, whatever the language of the content.
- Documentation is as visible as its project. Project permissions apply to the documentation. DokuWiki-Plugins is a public project, so the READMEs and
docsfiles of its packages are public too.
Rules in detail
The four tables below apply the principles to each kind of content, each documentation layer, each link direction, and each place.
Where content goes
| Content | Place |
|---|---|
| Overview, quickstart, tutorial, how-to, and troubleshooting for users and administrators; installation and updates; product concepts | Wiki, <lang>:wiki:dwe:<package>:* |
| Public interface, syntax and markup parameters, configuration keys with type and default, contracts | Repository, docs/api-reference.md and docs/contract-*.md, in English; in the wiki, <lang>:wiki:dwe:<package>:reference is the signpost |
| Requirements and dependencies | Repository, wkcomponent.json; the wiki shows them in the component matrix, generated from that file |
| Version history | Repository, CHANGELOG.md where a package keeps one, otherwise the commit history; never a wiki page |
| Decisions; engineering notes that record no decision | Repository, docs/adr/NNNN-<slug>.md; docs/notes/<slug>.md |
| Internal architecture, class and file map, storage internals | Repository, docs/architecture.md |
| Building, development environment, and tests of a single package | Repository, docs/development.md and CONTRIBUTING |
| Threat model | Repository, docs/threat-model.md |
| README | Repository, as a signpost: what the package is, links to its wiki pages, requirements, repository layout, development, changelog, license |
| The contribution path across projects: access, cloning, submitting a change, current state of the rules | Wiki, <lang>:wiki:help:projects:* |
Where each layer goes
The house documentation model assigns every page to one of six layers, L1 to L6.
| Layer | Place |
|---|---|
| L1 overview and entry page | Wiki |
| L2 tutorial and how-to | Wiki |
| L3 troubleshooting, with symptoms as headings | Wiki |
| L4 concepts | Wiki for product concepts; repository, docs/architecture.md, for internals |
| L5 reference for the public interface and configuration | Repository; the wiki links to it |
| L5 internal reference | Repository |
| L6 engineering notes, decisions, and changelog | Repository |
How to link
| Direction | How |
|---|---|
| From the wiki to the repository | Link to the project's repository screen, with the package's start page in the reader's language as the context, so that the interface stays in that language. Pattern: [[<lang>:wiki:dwe:<package>:start?do=wkdoadogit_repo&ns=code:dokuwiki-plugins:<package>&file=/docs/api-reference.md|…]]. The screen opens the default branch, main; you can choose other branches and individual commits there. Reading requires no account; cloning and downloading a ZIP archive require you to sign in. |
| From the repository to the wiki | An absolute link to the English page, for example https://www.wvds.it/wiki/doku.php?id=en:wiki:dwe:<package>:start. The language switcher on that page leads to the other four languages. |
| Not allowed | Repository files copied into the wiki as media files; repository files generated from wiki pages; repository files embedded in package pages |
Which language to use where
| Place | Language |
|---|---|
Repository: README, docs/**, CHANGELOG, CONTRIBUTING, code comments | English only |
| Wiki pages | German, English, and Slovenian. Each version is written in its own language from the verified facts and signed off by an editor for that language. Labels and messages are quoted exactly as the interface shows them in that language. |
| Work items, commit messages, pull request descriptions | German allowed |
| File names, folder names, namespaces, page IDs, media file names | Always English; the page IDs of the language versions differ only in the first segment |
Language resources
- House guide for English: Editorial guide – The White Knight Labs
- Normative basis: Microsoft Writing Style Guide; Merriam-Webster for spelling