¶ Style Guide
Style guide voor PMA v2 documentatie
¶ PMA v2 Style Guide
Deze style guide definieert de standaarden voor alle PMA v2 documentatie.
¶ Documentatie Principes
¶ 1. Rol-gebaseerd Schrijven
Elke pagina heeft een duidelijke doelgroep:
| Doelgroep | Taalgebruik | Focus |
|---|---|---|
| Management | Zakelijk, resultaatgericht | Waarde, ROI, risicos |
| Sales | Overtuigend, benefit-driven | USPs, differentiatie |
| Developers | Technisch, precies | Code, APIs, architectuur |
| Operators | Praktisch, actiegericht | Commands, procedures |
| Eindgebruikers | Eenvoudig, stap-voor-stap | Taken, workflows |
¶ 2. Structuur Conventies
Elke pagina bevat:
- H1 titel (eenmaal, bovenaan)
- Korte introductie (1-2 zinnen)
- Navigatie diagram of tabel
- Hoofd content
- Gerelateerde links onderaan
Voorbeeld structuur:
# Pagina Titel
Korte beschrijving van wat deze pagina behandelt.
---
## Sectie 1
Content...
## Sectie 2
Content...
---
*Gerelateerd: [Link 1](/path) | [Link 2](/path)*
¶ Mermaid Diagram Conventies
¶ Kleurenpalet
Gebruik consistente kleuren voor herkenbare categorieen:
¶ Categorie Kleuren
| Categorie | Hex Code | Gebruik |
|-----------|----------|---------||
| Core/Infrastructure | #1a5f7a | Authentik, Docker, MCP |
| Success/Active | #059669 | Running services, completed |
| Warning | #d97706 | Needs attention |
| Error/Critical | #dc2626 | Failures, problems |
| Info/Neutral | #2563eb | General information |
| Integration | #7b2cbf | Connections, workflows |
| Business | #2d6a4f | ERPNext, EspoCRM |
¶ Graph Types
1. Top-to-Bottom (TB) - Voor hierarchieen:
2. Left-to-Right (LR) - Voor processen:
3. Subgraphs - Voor categorisatie:
¶ Sequence Diagrams
Voor API flows en interacties:
¶ Best Practices
- Maximaal 10-12 nodes per diagram
- Altijd style directives voor consistente kleuren
- Quotes rond labels met spaties
- Subgraphs voor logische groepen
- Beschrijvende labels (niet "A", "B", "C")
¶ Veelvoorkomende Fouten
| Fout | Correct |
|------|---------||
| A[Label met spaties] | A["Label met spaties"] |
| Geen style directive | Altijd style X fill:#hex,color:#fff |
| Te veel nodes | Splits in meerdere diagrammen |
| Onduidelijke pijlen | Gebruik labels: A -->|actie| B |
¶ Link Conventies
¶ Interne Links
Altijd volledige paden gebruiken:
# CORRECT
[Services](/en/pma-v2/services)
[Architectuur](/en/pma-v2/architecture/overview)
# FOUT (relatieve paden)
[Services](../services)
[Services](/services)
¶ Navigatie Footer
Elke pagina eindigt met gerelateerde links:
---
**Navigatie:**
- Vorige: [Titel](/en/pma-v2/path)
- Volgende: [Titel](/en/pma-v2/path)
**Gerelateerd:**
- [Link 1](/en/pma-v2/path)
- [Link 2](/en/pma-v2/path)
¶ Code Voorbeelden
¶ Commands
# Altijd comment met beschrijving
just start redmine # Start de Redmine service
just health # Check health van alle services
¶ Configuratie
# Gebruik descriptive comments
name: service-name
version: "1.0"
# Uitleg bij complexe configuratie
settings:
key: value
¶ API Calls
# Altijd via localhost, nooit via tunnel URLs
curl -s "http://localhost:9114/issues.json" \
-H "X-Redmine-API-Key: $API_KEY"
¶ Tabel Conventies
¶ Standaard Tabel
| Kolom 1 | Kolom 2 | Kolom 3 |
|---------|---------|---------||
| Data | Data | Data |
¶ Command Reference Tabel
| Command | Beschrijving | Voorbeeld |
|---------|--------------|---------||
| just start X | Start service X | just start redmine |
¶ Vergelijkingstabel
| Feature | Optie A | Optie B |
|---------|:-------
:-------:||
| Feature 1 | Ja | Nee |
| Feature 2 | Ja | Ja |
¶ Emoji Gebruik
Minimaal emoji gebruik. Alleen voor:
| Emoji | Gebruik |
|-------|---------||
| Ja | Beschikbaar/Voltooid |
| Nee | Niet beschikbaar |
| Waarschuwing | Waarschuwing |
| Pin | Belangrijk |
¶ Kwaliteitscontrole Checklist
Voor elke pagina:
- H1 titel aanwezig en correct
- Intro paragraph aanwezig
- Mermaid diagrammen renderen correct
- Alle interne links werken (volledig pad)
- Geen hardcoded tenant URLs
- Consistente kleuren in diagrammen
- Nederlandse taal (tenzij technische termen)
- Navigatie footer aanwezig
- Code blocks met syntax highlighting
Gerelateerd: