Content Guidelines¶

Understanding the Diátaxis framework used in Airbase documentation

This document explains the documentation structure and style guidelines used throughout the Airbase documentation site.

Documentation Framework: Diátaxis¶

The Airbase documentation follows the Diátaxis framework, a systematic approach to technical documentation that divides content into four distinct types based on user needs and context. We've extended this with a fifth type—Examples—to provide complete, working implementations.

Why Diátaxis?¶

Diátaxis recognizes that documentation serves different purposes at different times: - Learning - When you're starting out and need guidance - Achieving goals - When you need to accomplish a specific task - Seeking information - When you need to look up technical details - Understanding - When you need to grasp concepts and context

By separating documentation into these categories, we make it easier for you to find what you need when you need it.

Documentation Types¶

1. Tutorials (Learning-Oriented)¶

Purpose: Guide newcomers through their first experience with Airbase

Characteristics: - Step-by-step instructions - Safe learning environment - Start from zero assumptions - Focus on getting users to a successful outcome - Provide concrete, repeatable steps

Browse tutorials: Tutorials Index

Example: Getting Started with Airbase

Content Guidelines for Tutorials: - Use second person ("you will...") - Provide expected output at each step - Use simple, complete examples - Guide users to success - Keep scope limited and achievable - Show, don't just tell - Ensure every step works

2. How-To Guides (Task-Oriented)¶

Purpose: Help users accomplish specific goals

Characteristics: - Goal-oriented (solve a specific problem) - Assume some knowledge - Provide a series of steps - Focus on results, not explanation - Flexible - show alternatives when helpful

Browse how-to guides: How-To Guides Index

Example: Build and Deploy Applications

Content Guidelines for How-To Guides: - Start with a clear goal - List prerequisites upfront - Use numbered steps - Focus on the task, not explanation - Provide working examples - Include troubleshooting for common issues

3. Reference (Information-Oriented)¶

Purpose: Provide authoritative technical specifications

Characteristics: - Accurate and authoritative - Consistently structured - Focused on description, not instruction - Comprehensive coverage - Regularly updated

Browse reference docs: Reference Index

Example: CLI Commands Reference

Content Guidelines for Reference: - Be precise and accurate - Use consistent formatting - Provide complete information - Include examples for clarity - Keep technical and factual - Maintain up-to-date information - Structure content predictably

4. Explanation (Understanding-Oriented)¶

Purpose: Clarify concepts and provide context

Characteristics: - Provide context and background - Discuss alternatives and trade-offs - Make connections between concepts - Explain design decisions - Help users think about the system - Don't instruct - discuss

Browse explanations: Explanation Index

Example: Airbase Console

Content Guidelines for Explanation: - Discuss, don't instruct - Provide context and background - Explain the "why" not just the "how" - Make connections to broader concepts - Discuss trade-offs and alternatives - Help users build mental models

5. Examples (Implementation-Oriented)¶

Purpose: Provide complete, working code that demonstrates real-world implementations

Characteristics: - Complete and working code - Ready to deploy - Well-documented - Follow best practices - Cover common use cases

Browse examples: Examples Index

Example: Node.js Express

Content Guidelines for Examples: - Provide complete, runnable code - Include all necessary configuration files - Document prerequisites and setup steps - Show best practices in action - Make code production-ready - Explain key implementation decisions

The Airbase documentation is organized according to these types:

docs/
├── tutorials/          # Learning-oriented
├── how-to/            # Task-oriented
├── reference/         # Information-oriented
├── explanation/       # Understanding-oriented
└── examples/          # Implementation-oriented

Writing Style Guidelines¶

General Principles¶

Clarity over cleverness: - Use simple, direct language - Avoid jargon unless necessary (and define it when used) - Write short sentences and paragraphs

Consistency: - Use the same terms throughout the documentation - Follow established formatting patterns - Maintain consistent command syntax

Accuracy: - Test all commands and code examples - Keep documentation in sync with platform changes - Remove outdated or hallucinated content

User-focused: - Anticipate user questions - Address common pain points - Provide context for decisions

Voice and Tone¶

Active voice: "Deploy your application" not "The application is deployed"

Second person: "You can view logs" not "Users can view logs" or "One can view logs"

Present tense: "The CLI builds the image" not "The CLI will build the image"

Positive framing: "Use Console to view logs" not "You cannot view logs via CLI"

Code Examples¶

All code examples must: - Be tested and working - Include necessary context - Show expected output when helpful - Use realistic (but safe) example data - Follow platform best practices

Example structure:

# Description of what this does
command with arguments

# Expected output:
# Success message or result

Formatting Conventions¶

Commands:

airbase container build
airbase container deploy --yes staging

File paths: - Absolute paths: /Users/username/project/airbase.json - Relative paths: ./src/index.js - Config files in project root: airbase.json, .env

Configuration examples:

{
  "framework": "container",
  "handle": "team/project",
  "port": 3000
}

Inline code: Use backticks for commands, file names, variables: airbase.json, PORT, npm install

Emphasis: - Bold for important terms first introduction - Italics sparingly for gentle emphasis - code formatting for technical terms

Cross-Referencing¶

Link between documentation types to help users navigate:

From Tutorials → How-To Guides: "Now that you've deployed your first app, learn how to set environment variables."

From How-To → Reference: "For complete command options, see CLI Commands Reference."

From Reference → Explanation: "To understand why Airbase uses this approach, see Architecture Explanation."

Maintenance Guidelines¶

Regular Reviews¶

Quarterly checks: - Verify all commands still work - Update version numbers and screenshots - Check for broken links - Review for outdated content

When platform changes: - Update affected documentation immediately - Add migration guides if needed - Mark deprecated features clearly

Removing Content¶

When to remove: - Commands that no longer exist (e.g., hallucinated airbase container logs) - Features that have been deprecated - Outdated workflows or best practices

How to remove: - Search entire documentation for all instances - Update cross-references - Consider adding redirect notes if widely referenced

Common Pitfalls to Avoid¶

❌ Don't Do This:¶

Mixing documentation types: - Don't put reference material in tutorials - Don't explain concepts in how-to guides - Don't provide step-by-step instructions in reference docs

Hallucinating features: - Don't document commands that don't exist - Don't assume CLI has features it doesn't - Verify every command before documenting

Over-explaining: - Tutorials: Don't deep-dive into theory - How-To Guides: Don't explain why, just show how - Reference: Don't provide walkthroughs

Inconsistent terminology: - Pick one term and stick with it - Example: "environment" not "env" sometimes and "environment" other times

✅ Do This:¶

Be explicit about documentation type: - Clear titles that indicate the document type - Consistent structure within each type - Cross-link when users need a different type

Test everything: - Run every command shown - Verify every code example - Check all file paths and URLs

Keep it current: - Update when platform changes - Remove deprecated content - Add new features promptly

Think about the user: - What are they trying to achieve? - What do they already know? - What will confuse them?

Getting Help¶

For Documentation Contributors¶

Before writing: 1. Identify which Diátaxis type fits your content 2. Review existing examples of that type 3. Check the relevant content guidelines above

While writing: 1. Follow the style guide consistently 2. Test all commands and examples 3. Cross-reference related content

After writing: 1. Have someone else test your instructions 2. Check for broken links 3. Verify formatting renders correctly