STYLE GUIDE

FlowX.AI Documentation Style Guide

A comprehensive guide for writing, structuring, and maintaining FlowX.AI documentation.

---

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

Every piece of documentation must answer: “What problem does this solve for the reader?”

Avoid “documentation theater” — writing docs just because they’re expected. If you can’t identify the user need, question whether the doc should exist.

Hierarchy of priorities

Focus efforts in this order:

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

The best documentation doesn’t draw attention to itself. Users should solve their problem and move on, not remember the docs — just the success.

---

Audience

Primary audiences

Audience	Technical level	Goals
Platform administrators	High	Configure, deploy, maintain FlowX
Process designers	Medium	Build workflows, configure UI
Developers	High	Integrate APIs, customize renderers
Business analysts	Low-Medium	Understand capabilities, design processes

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

Do	Don’t
Direct and clear	Verbose or flowery
Confident but not arrogant	Condescending
Helpful and supportive	Dismissive of user struggles
Professional	Overly casual or stiff

Tone by context

Context	Tone
Tutorials/Getting started	Encouraging, patient
Reference docs	Precise, neutral
Troubleshooting	Empathetic, solution-focused
Release notes	Informative, concise
Warnings	Serious but not alarming

Active voice

Use active voice. It’s clearer and more direct.

❌ "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

Address the reader directly as “you.”

❌ "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

Use lists when you have:

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

Bulleted lists — for unordered items:

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

Numbered lists — for sequential steps (1-2 steps only; use Steps component for 3+):

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

Clarity techniques

Technique	Example
Specific over vague	”within 30 seconds” not “quickly”
Concrete over abstract	”click Save” not “persist your changes”
Simple words	”use” not “utilize”, “start” not “initiate”
Consistent terminology	Pick one term and stick with it

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

User need	Content type
”What is this?”	Overview / Concept doc
”How do I start?”	Getting Started guide
”How do I do X?”	Tutorial / How-to
”What are the options?”	Reference doc
”Why isn’t it working?”	Troubleshooting
”What changed?”	Release notes
”What’s recommended?”	Best practices

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

Every API endpoint needs these 5 sections:

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

Include these supporting docs:

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

Example format:

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

Parameter documentation

For each parameter, document:

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

Group parameters by type:

• 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

Element	Format
UI buttons/tabs	Bold: Click Save
Menu paths	Arrows: Settings → Access
Code/values	Backticks: value
File paths	Backticks: /config/application.yaml
Env variables	Backticks: REDIS_HOST
Placeholders	Curly braces: {your-api-key}
Keyboard shortcuts	Plus sign: Ctrl+S

Terminology standards

Use	Don’t use
app	application
turn on/off	enable/disable
set up (verb)	setup (as verb)
log in (verb)	login (as verb)
email	e-mail
API	api, Api

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

Track documentation effectiveness through:

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

Deprecation

When removing or replacing content:

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

---

Last updated: February 2026