​

FlowX.AI Documentation Style Guide

​

Table of contents

1. Philosophy & principles
2. Audience
3. Voice & tone
4. Writing guidelines
5. Content types
6. Structure patterns
7. Formatting reference
8. Quality checklist

​

Philosophy & principles

​

Core principle: Solve a need, not check a box

​

Hierarchy of priorities

1. Coverage — Document ~80% of capabilities (complete coverage is impossible)
2. Usefulness — Does it solve problems and reduce friction?
3. Freshness — Is it current and accurate?
4. Discoverability — Can users find it when needed?
5. Aesthetics — Visual polish (last priority, not first)

​

Minimum Viable Documentation (MVD)

• Ship “good enough” docs early
• Iterate based on feedback
• Something useful > something perfect but delayed
• Accept imperfection — docs can never be perfect

​

The invisibility goal

​

Audience

​

Primary audiences

​

Writing for your audience

• Don’t assume shared mental models — explain context
• Qualify complexity by experience level — “If you’re familiar with Kafka…”
• Avoid “easy” or “just” — what’s easy for you may not be for them
• Include prerequisites — help readers self-assess if content is for them

​

Voice & tone

​

Voice characteristics

​

Tone by context

​

Active voice

❌ "The process is started by clicking the button"
✅ "Click the button to start the process"

❌ "The configuration file should be edited"
✅ "Edit the configuration file"

​

Second person

❌ "Users can configure the setting..."
✅ "You can configure the setting..."

❌ "One should ensure that..."
✅ "Ensure that..."

​

Writing guidelines

​

Sentence structure

• Keep sentences short — aim for 15-25 words
• One idea per sentence
• Lead with the action in procedural content
• Front-load important information

❌ "In order to be able to configure the Redis cache, you will first need to ensure that you have the proper access rights."

✅ "Before configuring Redis cache, verify you have admin access rights."

​

Paragraph structure

• One topic per paragraph
• 2-4 sentences per paragraph for readability
• Use the inverted pyramid — most important info first

​

Lists

• 3+ related items
• Sequential steps
• Options or alternatives

Key features:
- Real-time process monitoring
- Drag-and-drop interface
- Role-based access control

1. Open the configuration file.
2. Update the `API_KEY` value.

​

Clarity techniques

​

What to avoid

• Jargon without explanation — define terms on first use
• Passive voice — unless the actor is unknown/irrelevant
• Future tense — use present tense for features that exist
• Marketing language — “revolutionary”, “seamless”, “best-in-class”
• Humor — it doesn’t translate well and ages poorly
• Absolutes — “always”, “never” (unless truly absolute)

​

Content types

​

Decision matrix: What to write

​

Content type definitions

​

Overview / Concept

• Purpose: Explain what something is and why it matters
• Length: 200-500 words
• Include: Definition, use cases, key benefits, diagram
• Avoid: Step-by-step instructions (link to tutorials instead)

​

Getting Started

• Purpose: First successful experience with a feature
• Target: Completable in 5-15 minutes
• Include: Prerequisites, minimal steps, success validation
• Principles:
  • End-to-end workflow, simplest possible output
  • Minimize setup friction (sandboxes, sample data)
  • Include troubleshooting for common first-time errors
  • Teach concepts while doing

​

Tutorial / How-to

• Purpose: Guide through a specific task
• Structure: Prerequisites → Steps → Validation → Next steps
• Include: Code samples, screenshots at decision points
• Principles:
  • One task per tutorial
  • Test every step yourself
  • Include expected output at key steps

​

Reference

• Purpose: Comprehensive details for lookup
• Structure: Organized for scanning (tables, lists)
• Include: All parameters, options, defaults, constraints
• Principles:
  • Complete > concise
  • Consistent structure across all reference docs
  • Group logically (by function, not alphabetically)

​

Troubleshooting

• Purpose: Help users recover from problems
• Structure: Symptom → Cause → Solution
• Include: Error messages (exact text), diagnostic steps
• Principles:
  • Lead with the symptom (what user sees)
  • Actionable solutions, not just explanations
  • Test solutions work

​

Release notes

• Purpose: Communicate changes between versions
• Include: New features, improvements, bug fixes, breaking changes
• Principles:
  • User-facing changes only (not internal refactoring)
  • Link to detailed docs, don’t repeat them
  • Clear upgrade path for breaking changes

​

Best practices

• Purpose: Guidance for optimal usage
• Include: Recommendations, rationale, examples
• Principles:
  • Explain why, not just what
  • Based on real-world usage patterns
  • Update as product evolves

​

Structure patterns

​

API/Integration documentation

1. Resource description — What it does, when to use it
2. Endpoint and method — GET /api/v1/processes
3. Parameters — All params with type, required/optional, defaults
4. Request example — Working curl or code sample
5. Response example — Typical response with schema

​

Conceptual topics for APIs

1. Product overview
2. Getting started (5-15 min)
3. Authentication & authorization
4. Status & error codes (standalone page)
5. Rate limiting (if applicable)
6. Quick reference / cheat sheet
7. Glossary
8. Best practices

​

Error code documentation

• Create a standalone page for all error codes
• Focus on custom codes specific to FlowX (standard HTTP codes need less explanation)
• Include recovery actions — not just definitions
• Test by breaking things — intentionally trigger errors to document them

| Code | Message | Cause | Solution |
|------|---------|-------|----------|
| FX-4001 | Invalid process definition | Process JSON is malformed | Validate JSON syntax and required fields |

​

Parameter documentation

• Data type (string, integer, boolean, object, array)
• Required or optional
• Default value
• Allowed values / constraints
• Example value

• Path parameters
• Query parameters
• Header parameters
• Request body

​

Setup guide structure

1. Overview (what this configures)
2. Prerequisites
3. Configuration
   - Environment variables table
   - Example configuration
4. Validation steps
5. Troubleshooting
6. Related resources

​

Formatting reference

See CLAUDE.md for complete Mintlify component reference.

​

Quick reference

​

Terminology standards

​

Headings

• Sentence case: “Configure the database connection”
• No period at end
• Front-load keywords for scanning
• Use parallel structure in lists of headings

​

Quality checklist

​

Before writing

• Identified the user need this doc solves
• Checked for existing docs on this topic
• Determined the right content type
• Identified target audience

​

While writing

• Used active voice
• Addressed reader as “you”
• Kept sentences under 25 words
• Included examples for complex concepts
• Tested all code samples and procedures
• Added screenshots at decision points (not every step)

​

Before publishing

• Spell-checked and grammar-checked
• Verified all links work
• Added to docs.json navigation
• Wrapped images in <Frame>
• Included frontmatter (title, description)
• Added version callout if feature is version-specific
• Cross-linked to related docs

​

Content quality

• Answers “what problem does this solve?”
• Completable in reasonable time (Getting Started: 5-15 min)
• No “documentation theater” — genuinely useful
• No marketing language
• Accurate and testable

​

Accessibility

• Images have alt text
• Tables have headers
• Color is not the only indicator
• Code blocks have language specified

​

Maintenance

​

When to update docs

• New feature released
• Feature behavior changed
• User feedback indicates confusion
• Support tickets show recurring questions
• API endpoints modified

​

Docs observability

• User journey from docs → product success
• Support ticket reduction after doc updates
• Time to first successful API call
• Feedback and ratings (if available)

​

Deprecation

1. Add deprecation notice with alternative
2. Keep old content accessible for transition period
3. Update all internal links
4. Remove from navigation after transition

​

Resources

​

External style guides for reference

• Google Developer Documentation Style Guide
• Microsoft Writing Style Guide
• Mailchimp Content Style Guide

​

Recommended reading

• I’d Rather Be Writing — API documentation best practices
• passo.uno — Technical writing strategy and AI integration