<markdown>
---
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.**

| Area | Audience | Focus |
|------|----------|-------|
| **developer** | Entwickler | APIs, SDKs, code examples, integration |
| **administrator** | Sysadmin | Installation, configuration, operations, monitoring |
| **user** | Anwender | How-to guides, tutorials, UI workflows |
| **business** | Kaufmann | Use cases, ROI, compliance, decision support |

**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

```dokuwiki
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:

```dokuwiki
====== 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

```dokuwiki
====== 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
| Role | Description |
|------|-------------|
| Master | Source language, all content originates here |
| Translation | Derived from master, same structure |

### 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
```dokuwiki
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
| Type | Examples |
|------|----------|
| Standards | NIST, ISO, IETF RFCs, OASIS |
| Legal | EUR-Lex, national law databases |
| Official | Government agencies (BSI, ENISA) |

---

## 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.
</markdown>