How FrameworX documentation combines Diátaxis framework with module-centric navigation and AI-optimized content.
Platform → Technology → Supporting → Documentation Structure and Design Philosophy
Why Documentation Structure Matters
FrameworX 10.1 documentation follows the Diátaxis framework—not as an academic exercise, but to solve real problems. Engineers need different types of information at different times: learning concepts, following tutorials, solving specific problems, or looking up technical details. Our documentation structure ensures you find exactly what you need, when you need it, whether you're a human reader or an AI assistant parsing the content.
The Diátaxis Framework
Diátaxis defines four distinct documentation types, each serving a specific purpose:
| Type | Purpose | When You Need It | Example |
|---|---|---|---|
| Tutorials | Learning by doing | First time with the platform | Build your first HMI display |
| Concepts | Understanding why | Need context and theory | How alarms state management works |
| How-to Guides | Solving specific problems | Have a task to complete | Configure alarm email notifications |
| Reference | Technical specifications | Need precise details | Alarm API methods and properties |
Each documentation type answers a different question:
- Tutorial: "How do I get started?"
- Concept: "Why does it work this way?"
- How-to: "How do I accomplish X?"
- Reference: "What are the exact specifications?"
Mixing these types creates confusion. Keeping them separate ensures clarity.
Our Hybrid Implementation
While strictly following Diátaxis principles, we recognize that engineers often think in terms of modules. Our hybrid approach provides both navigation paths:
Module-Centric Navigation
Navigate to any module (Alarms, Historian, Displays) and find all four documentation types:
- Alarms Module
- Tutorial: Build alarm configuration from scratch
- Concept: Understand alarm state management
- How-to: Configure specific alarm features
- Reference: Complete API and configuration tables
Type-Centric Navigation
Or browse by documentation type across all modules:
- All Tutorials - Learning paths for every module
- All Concepts - Theoretical foundations
- All How-to Guides - Problem-solving recipes
- All References - Technical specifications
This dual navigation ensures users can follow their natural workflow, whether exploring a specific module or seeking a particular type of information.
AI-Optimized Content Design
Every design decision supports both human comprehension and machine parsing:
Diagrams Over Screenshots
| Traditional Approach | Our Approach | Why |
|---|---|---|
| Screenshots everywhere | Tables and diagrams | Machine-readable, version-independent |
| UI-specific instructions | Conceptual workflows | Resilient to UI changes |
| Binary images | SVG/HTML5 graphics | Searchable, scalable, accessible |
Image Inclusion Rule
When We Include Images
Rule: Include an image only if it conveys information that text or diagrams cannot express clearly.
Examples where images add value:
- Complex P&ID displays showing spatial relationships
- Runtime visualization examples
- Color-coded alarm states
Language Precision
FrameworX 10.1 underwent comprehensive terminology review:
- Consistent naming - Same term everywhere for same concept
- Technical accuracy - Precise without being pedantic
- Future-proof - Terms that work for AI parsing
- Clear hierarchy - Parent-child relationships explicit
Documentation Standards
Page Structure
- One-liner - Single sentence describing page purpose
- Breadcrumbs - Complete navigation path
- Introduction - Context before details
- Progressive disclosure - General to specific
Content Principles
- Direct language - No unnecessary adjectives
- Technical focus - Function over form
- Practical examples - Real-world applications
- Cross-references - Link related concepts
Supporting AI Assistants
This structure directly enables AI capabilities:
Semantic Understanding
- Consistent terminology enables accurate responses
- Clear categorization helps identify intent
- Structured content improves context retrieval
MCP Integration Benefits
- AI can distinguish tutorial from reference content
- Structured diagrams enable visual generation
- Consistent patterns improve answer quality
Practical Benefits for Users
| User Challenge | How Structure Helps |
|---|---|
| "Where does tutorial end and how-to begin?" | Clear separation with distinct purposes |
| "I need all alarm information" | Module view consolidates all types |
| "Just tell me how to do X" | How-to guides isolated from theory |
| "I need to understand the architecture" | Concept pages without implementation details |
Navigation Patterns
Three complementary navigation methods:
- Module-based - All content for one module
- Type-based - All content of one type
- Task-based - Cross-module workflows
Each path leads to the same content, organized for different mental models.
Continuous Improvement
This structure evolves based on:
- User navigation patterns
- AI query analysis
- Support ticket themes
- Community feedback
The framework remains stable while content continuously improves.
In this section...