---

name: writing-dokuwiki-documentation

description: Creates and maintains multi-language documentation in DokuWiki format. Handles structure planning, navigation sorting, cross-references, footnotes with trusted sources, and translations. Use when creating wiki documentation, planning doc structure, or translating existing content.

DokuWiki Documentation Guide

Audience-Based Structure

Organize documentation by target audience when applicable.

When to use: Products with multiple user roles or technical complexity.

---

Workflow: Plan Before Write

ALWAYS plan structure before writing content.

1. Identify audiences - Which of the 4 areas apply?
2. Define hierarchy - Areas → Sections → Pages
3. Number sections - For navigation sorting (1., 2., 3.)
4. Map cross-references - Which pages link to which?
5. Identify shared concepts - Write once, link everywhere
6. Then write content - Following the plan

---

Avoiding Redundancy

Don't Repeat - Link Instead

BAD:  Explain TLS 1.3 on every page
GOOD: Explain once, then [[security:tls|see TLS configuration]]

Shared Concepts Pattern

1. Create a reference page for shared concepts
2. Link to it from all pages that use the concept
3. Keep details in one place only

Cross-Reference Planning

Before writing, create a reference map:

Page A → links to → Page B, Page C
Page B → links to → Page A
Concept X → explained in → Page D (link from A, B, C)

---

Navigation Sorting

DokuWiki sorts alphabetically. Use numbered prefixes for logical order:

====== 1. Installation ======
====== 2. Configuration ======
====== 3. Operations ======

Rule: Number only the H1 title in start.txt files.

---

Content Principles

Public Documentation Rules

This is public documentation. NEVER include:

• Pricing, costs, or licensing fees
• Project effort, timelines, or resource estimates
• Internal business information
• Competitive comparisons with pricing

Page Length

~1500 characters / ~250 words (1 DIN-A4 page)

Funnel Principle (Trichterprinzip)

Structure each page from broad to detailed:

1. Overview - What? Why?
2. Key Points - Main concepts
3. Details - Step-by-step
4. References - Links to related pages

---

DokuWiki Syntax

====== H1 Title ======
===== H2 Section =====
==== H3 Subsection ====
 
^ Header ^ Header ^              Tables
| Cell   | Cell   |
 
[[namespace:page|Text]]          Internal links
[[section:start|Section Home]]   Link to section
 
Begriff((Source: URL))           Footnotes

---

Multi-Language Documentation

Roles

Source Priority for References

Prefer current language. Fallback to English.

Example for EUR-Lex:

EN: https://eur-lex.europa.eu/eli/reg/2022/2554/oj
DE: https://eur-lex.europa.eu/eli/reg/2022/2554/oj?locale=de

Translation Workflow

1. Create structure first - All start.txt with numbered H1
2. Keep technical terms - Don't translate: API, TLS, OData, GraphQL
3. Translate content - Following master structure
4. Adapt sources - Use language-appropriate references

---

Path Structure

{project}/{lang}/{product}/{area}/{section}/start.txt
{project}/{lang}/{product}/{area}/{section}/page-name.txt

Naming Conventions

• Folders: lowercase, hyphens (e.g., first-steps)
• Files: lowercase, hyphens, .txt extension
• Entry point: always start.txt

---

Footnotes with Sources

When to Use

• Technical standards (NIST, IETF, ISO)
• Legal references (regulations, directives)
• Official specifications

Format

ML-KEM((NIST FIPS 203: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf))
NIS2((EUR-Lex: https://eur-lex.europa.eu/eli/dir/2022/2555/oj))

Trusted Source Types

---

Example: Planning a Documentation Set

Step 1: Identify Audiences

✓ developer    - needs API docs, code examples
✓ administrator - needs installation, config, operations
✓ user         - needs Excel/Power BI tutorials
✓ business     - needs use cases, ROI, compliance

Step 2: Define Structure

developer/
  1. rest-api/
  2. odata/
  3. examples/
  4. security/
administrator/
  1. installation/
  2. configuration/
  3. operations/
  4. security/
user/
  1. excel/
  2. powerbi/
  3. security/
business/
  1. usecases/
  2. integration/
  3. security/

Step 3: Map Cross-References

installation → configuration → operations (flow)
all areas → security/ (shared concept per audience)
developer/security ←→ administrator/security (cross-link)

Step 4: Identify Shared Concepts

"TLS Configuration" → developer/security/tls.txt (technical)
                    → administrator/security/tls.txt (operational)
                    → business/security/compliance.txt (summary)
→ Each audience gets appropriate depth, link between them

Step 5: Write Content

Following funnel principle, with planned links.