| name | netex-nordic-doc-guides |
| description | Complete rules for writing conceptual Guides (guides/) in the Nordic NeTEx Profile. Covers section structure, tone, length, formatting, and cross-referencing. Self-contained — no external files needed. |
Guides — Documentation Rules
What is a guide?
Guides are conceptual documents aimed at human readers — they explain why and how, not just what.
Unlike Object/Frame documentation (structural, specification-oriented), Guides teach concepts,
explain patterns, and provide worked examples spanning multiple objects.
Folder structure
guides/
└── <GuideName>/
├── <GuideName>_Guide.md ← Main guide document (required)
├── Example_<Topic>.xml ← Validated XML example (recommended)
└── images/ ← Diagrams, SVGs (optional)
Section structure
Guides are more flexible than Object/Frame docs — section names and count may vary.
Recommended progression (adapt to fit the topic):
1. Introduction (required)
2–4 sentences explaining the topic and why it matters. Assume the reader knows NeTEx basics but not this specific topic.
Include a "what you'll learn" summary:
In this guide you will learn:
- 🎯 What separation of concerns means in NeTEx
- 🧩 The three coupling strategies
- 🗂️ How frames map to domains
- 📝 Practical XML examples
2. Core Concepts (recommended)
The conceptual foundation — explain the why before the how.
Mix of:
- Prose for explanation
- Tables for comparisons/trade-offs
- Mermaid diagrams for relationships and flows
- SVG images for complex visuals
<details> sections for advanced content that might overwhelm newcomers
3. How It Works in NeTEx (recommended)
Map concepts to concrete NeTEx objects, frames, and references.
Include:
- Domain/Object mapping tables
- Frame mapping (which frames carry which data)
- Reference patterns (how objects link across domains)
- XML snippets with inline comments
4. Practical Examples (required)
Complete, validated XML examples with narrative explanation.
- Reference full examples:
📄 **Full example:** [Example_Topic.xml](Example_Topic.xml)
- Inline snippets: show only the relevant fragment, not the full PublicationDelivery wrapper
- Include inline comments explaining key decisions
5. Best Practices (recommended)
Actionable recommendations. Use > [!TIP] callout with bullet points, or ✅/❌ do/don't lists.
6. Related Resources (recommended)
Links to related guides, frame/object documentation, and external references:
## Related Resources
### Guides
- [Calendar](../Calendar/Calendar_Guide.md) – Date-based scheduling
### Objects & Frames
- [ServiceJourney](../../objects/ServiceJourney/Table_ServiceJourney.md) – Journey definitions
- [TimetableFrame](../../frames/TimetableFrame/Table_TimetableFrame.md) – Journey scheduling
### External
- [NeTEx CEN Standard](https://www.netex-cen.eu/) – Official specification
Hard rules (always apply regardless of section structure)
- Start with an introduction that sets context
- Include at least one validated XML example
- Use flexible-alerts syntax (
> [!TIP], > [!NOTE], > [!WARNING]) — never emoji callouts
- Use Mermaid or SVG for diagrams (follow palettes in
netex-nordic-doc-visual skill)
- Cross-reference related Object/Frame Table files with relative links
- Keep paragraphs short (3–5 sentences)
- All XML must be validated against XSD
- When a guide covers objects not yet documented in the Nordic Profile, flag them explicitly with a
> [!WARNING] callout noting their status (e.g. "undocumented", "proposed", or "diverges from published profile")
Tone & audience
- Write for human readers first (practitioners, architects, developers)
- Assume familiarity with NeTEx basics but not the specific topic
- Use active voice and second person ("you")
- Sentence case everywhere
- 24-hour time: 07:42, 14:15
- En-dash for pairs: Oslo S – Bergen
- Middle dot as separator: 3 changes · 6 h 32 min
Length
- Target: 400–1200 words (excluding XML examples and tables)
- Guides may be longer than Object/Frame descriptions — depth is expected
- Completeness is preferred over truncation — especially for complex topics (e.g. rolling stock, compound trains)
- If a guide exceeds ~2000 words, consider splitting into sub-guides
Cross-referencing
- Relative links to Table files for structural reference
- Relative links to Description files for conceptual context
- Always verify links resolve to existing files
- Use docsify tabs for profile-specific comparisons (MIN vs NP)
Quality checklist
