User Documentation

This document defines the standards and processes for maintaining comprehensive user documentation for the Flowstate application.

Table of Contents

1. Overview
2. Documentation Types
3. Help Center Integration
4. Screenshot Standards
5. Workflow Guides
6. Automation Process
7. Maintenance Lifecycle
8. Documentation Templates

Overview

All dashboard screens and features will have associated documentation in the Help Center. This documentation serves as the primary reference for users to understand functionality, complete workflows, and troubleshoot issues.

Core Principles

• Completeness: Every feature has corresponding documentation
• Currency: Documentation is updated with every feature change
• Accessibility: Documentation is easily discoverable from within the application
• Visual: Screenshots and visual guides accompany text instructions
• Automation: Documentation updates are integrated into the development workflow

Documentation Types

1. Feature Documentation

Comprehensive guides for each major feature area:

2. Workflow Guides

Step-by-step instructions for completing common tasks:

• Creating a new event
• Submitting deliverables for approval
• Generating reports
• Managing user permissions
• Configuring notifications

3. Quick Reference Cards

Single-page summaries for rapid lookup:

• Keyboard shortcuts
• Status definitions
• Role permissions matrix
• Common error resolutions

4. Release Notes

User-facing summaries of changes:

• New features
• Improvements
• Bug fixes
• Breaking changes

5. FAQ

Frequently asked questions organized by topic:

• Account & Access
• Events & Deliverables
• Reports & Analytics
• Troubleshooting

Help Center Integration

In-App Help Links

Every screen includes contextual help access:

// Component pattern for help integration
interface HelpLinkProps {
  articleId: string;
  section?: string;
}

const HelpLink: React.FC<HelpLinkProps> = ({ articleId, section }) => {
  const helpUrl = `/help/articles/${articleId}${section ? `#${section}` : ''}`;
  return (
    <a href={helpUrl} target="_blank" rel="noopener noreferrer">
      <HelpCircle className="h-4 w-4" />
    </a>
  );
};

Article ID Convention

{feature-area}-{topic}-{subtopic}

Examples:
- events-create-basic
- events-create-deliverables
- reports-export-pdf
- admin-users-permissions

Help Center Structure

help/
├── getting-started/
│   ├── overview.md
│   ├── first-login.md
│   └── navigation.md
├── events/
│   ├── overview.md
│   ├── creating-events.md
│   ├── managing-deliverables.md
│   └── event-timeline.md
├── reports/
│   ├── overview.md
│   ├── generating-reports.md
│   └── exporting-data.md
├── admin/
│   ├── user-management.md
│   ├── permissions.md
│   └── settings.md
└── troubleshooting/
    ├── common-issues.md
    └── error-codes.md

Screenshot Standards

Capture Requirements

Annotation Guidelines

1. Callouts: Use numbered circles (1, 2, 3) for sequential steps
2. Highlights: Red borders (#EF4444) for areas of focus
3. Arrows: Directional arrows for flow indication
4. Text Labels: Clear, concise labels in sans-serif font

File Naming Convention

{feature}_{action}_{step-number}_{description}.png

Examples:
- events_create_01_open-form.png
- events_create_02_fill-details.png
- events_create_03_add-deliverables.png
- events_create_04_submit.png

Screenshot Directory Structure

docs/screenshots/
├── events/
│   ├── create/
│   ├── edit/
│   └── view/
├── reports/
│   ├── generate/
│   └── export/
├── admin/
│   ├── users/
│   └── settings/
└── common/
    ├── navigation/
    └── notifications/

Workflow Guides

Guide Template

Each workflow guide follows this structure:

# [Action] [Feature]

## Overview
Brief description of what this workflow accomplishes.

## Prerequisites
- Required permissions
- Required data/setup
- Related features

## Steps

### Step 1: [Action]
[Description]
![Screenshot](./screenshots/feature_action_01.png)

### Step 2: [Action]
[Description]
![Screenshot](./screenshots/feature_action_02.png)

## Expected Results
What the user should see upon completion.

## Troubleshooting
Common issues and resolutions.

## Related Topics
- [Related Guide 1](./related-1.md)
- [Related Guide 2](./related-2.md)

Workflow Checklist

Before publishing a workflow guide:

• [ ] All steps are numbered sequentially
• [ ] Screenshots match current UI
• [ ] Prerequisites are clearly stated
• [ ] Expected results are defined
• [ ] Troubleshooting section addresses common issues
• [ ] Related topics are linked
• [ ] Reviewed by QA
• [ ] Reviewed by product owner

Automation Process

Screenshot Automation

Screenshots are automatically captured during E2E test runs:

// e2e/utils/documentation.ts
export async function captureDocScreenshot(
  page: Page,
  feature: string,
  action: string,
  step: number,
  description: string
): Promise<void> {
  const filename = `${feature}_${action}_${step.toString().padStart(2, '0')}_${description}.png`;
  const filepath = `docs/screenshots/${feature}/${action}/${filename}`;

  await page.screenshot({
    path: filepath,
    fullPage: false,
  });
}

Documentation Generation Pipeline

# .github/workflows/docs.yml
name: Documentation

on:
  push:
    paths:
      - 'src/**'
      - 'e2e/**'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm ci

      - name: Run documentation tests
        run: npm run test:e2e:docs

      - name: Generate screenshots
        run: npm run docs:screenshots

      - name: Update help articles
        run: npm run docs:update

      - name: Commit changes
        run: |
          git config user.name "Documentation Bot"
          git config user.email "docs@bot.local"
          git add docs/
          git commit -m "docs: update documentation" || exit 0
          git push

Change Detection

Documentation updates are triggered when:

1. Component Changes: UI components modified
2. Route Changes: Navigation structure updated
3. Feature Additions: New features added
4. Feature Removals: Features deprecated or removed

// scripts/detect-doc-changes.ts
interface DocChange {
  type: 'add' | 'modify' | 'remove';
  feature: string;
  files: string[];
  requiredUpdates: string[];
}

async function detectDocumentationChanges(
  changedFiles: string[]
): Promise<DocChange[]> {
  const changes: DocChange[] = [];

  // Map file changes to documentation requirements
  for (const file of changedFiles) {
    if (file.includes('src/views/')) {
      const feature = extractFeatureFromPath(file);
      changes.push({
        type: 'modify',
        feature,
        files: [file],
        requiredUpdates: [
          `docs/help/${feature}/overview.md`,
          `docs/screenshots/${feature}/`,
        ],
      });
    }
  }

  return changes;
}

Maintenance Lifecycle

Documentation Review Cycle

Version Alignment

Documentation versions align with application releases:

docs/
├── v2.0/           # Current version
├── v1.9/           # Previous version
└── archive/        # Older versions

Deprecation Process

When features are deprecated:

1. Mark documentation as deprecated
2. Add migration guidance
3. Maintain for 2 release cycles
4. Archive after removal

> **Deprecated**: This feature will be removed in v3.0.
> See [Migration Guide](./migration.md) for alternatives.

Documentation Templates

Feature Overview Template

# [Feature Name]

## What is [Feature]?
Brief description of the feature and its purpose.

## Key Capabilities
- Capability 1
- Capability 2
- Capability 3

## Getting Started
Link to quickstart guide.

## Common Tasks
- [Task 1](./task-1.md)
- [Task 2](./task-2.md)

## Best Practices
Recommendations for effective use.

## FAQ
Link to feature-specific FAQ.

How-To Guide Template

# How to [Action]

**Time Required**: X minutes
**Skill Level**: Beginner/Intermediate/Advanced
**Prerequisites**: List requirements

## Overview
What this guide covers.

## Steps

### 1. [First Step]
Description and screenshot.

### 2. [Second Step]
Description and screenshot.

## Verification
How to confirm success.

## Next Steps
What to do after completing this task.

Troubleshooting Template

# Troubleshooting: [Issue Category]

## [Error/Issue Name]

### Symptoms
- What the user sees
- Error messages

### Cause
Why this happens.

### Solution
Step-by-step resolution.

### Prevention
How to avoid this issue.

Quality Metrics

Documentation Health Indicators

Automated Checks

// scripts/validate-docs.ts
interface DocValidation {
  file: string;
  issues: string[];
  isValid: boolean;
}

async function validateDocumentation(): Promise<DocValidation[]> {
  const results: DocValidation[] = [];

  // Check for broken links
  // Verify screenshot existence
  // Validate required sections
  // Check for outdated content markers

  return results;
}

Tools and Resources

Recommended Tools

Style Guide

• Use active voice
• Keep sentences concise
• Use numbered lists for sequential steps
• Use bullet lists for non-sequential items
• Include screenshots for visual guidance
• Define technical terms on first use
• Link to related documentation

Package Documentation System

Overview

The documentation site automatically aggregates documentation from individual packages in the monorepo. Each package can enable documentation by adding configuration and markdown files.

Enabling Documentation for a Package

1. Add documentation config

Add a documentation section to your package's .flowstate/config.json:

{
  "documentation": {
    "enabled": true,
    "type": "app",
    "title": "Your Package Title",
    "description": "Brief description",
    "category": "apps",
    "order": 1
  }
}

Configuration fields:

Categories:

• apps - User-facing applications
• core - Core libraries
• integrations - External service integrations
• tools - CLI tools and utilities

2. Create documentation files

Create a .flowstate/docs/ directory in your package with at minimum an index.md file:

packages/your-package/.flowstate/
└── docs/
    └── index.md    # Required: Package overview

Use the templates at .flowstate/templates/documentation/:

• app/ - Template for user-facing applications
• library/ - Template for developer libraries

IMPORTANT - Subdirectory Structure Required:

Next.js App Router requires each documentation page (except the root index.md) to be in its own subdirectory. The sync script renames index.md files to page.md for routing.

docs/
├── index.md                          # Root page (stays as index.md)
├── getting-started/
│   └── index.md                      # -> getting-started/page.md
├── features/
│   └── index.md                      # -> features/page.md
├── workflows/
│   └── my-workflow/
│       └── index.md                  # -> workflows/my-workflow/page.md
└── troubleshooting/
    └── index.md                      # -> troubleshooting/page.md

DO NOT create flat files like getting-started.md directly in the docs folder - they will result in 404 errors.

3. Run the sync script

yarn workspace @epicdm/flowstate-docs docs:sync

This will:

1. Discover packages with documentation.enabled: true
2. Copy markdown files to the documentation site
3. Generate API docs from TSDoc (libraries only)
4. Update the navigation manifest

Markdown Frontmatter

Each markdown file should include YAML frontmatter:

---
title: Page Title
order: 1
description: Brief page description
---

• title - Display title in navigation and page header
• order - Sort order (lower numbers appear first)
• description - Used in search and metadata

Code Block Requirements

All code blocks MUST have a language identifier. The documentation site uses syntax highlighting that requires a language to be specified. Code blocks without a language will cause runtime errors.

<!-- CORRECT -->
```typescript
const x = 1;
```text

<!-- CORRECT - use 'text' for ASCII diagrams -->
```text
┌─────────┐
│  Box    │
└─────────┘
```text

<!-- INCORRECT - will cause errors -->

const x = 1;

Common language identifiers:

TSDoc API Documentation

For library packages (type: "library"), the sync script automatically extracts API documentation from TSDoc comments in your TypeScript source files.

Supported TSDoc tags:

• @description / description text - Function/class description
• @param - Parameter documentation
• @returns - Return value documentation
• @example - Code examples

Build Integration

Documentation sync runs automatically before the docs site build:

# Manual sync
yarn workspace @epicdm/flowstate-docs docs:sync

# Build (runs sync first via prebuild hook)
yarn workspace @epicdm/flowstate-docs build

Generated Files

The following files are auto-generated and gitignored:

• packages/documentation/src/app/docs/*/ - Copied package docs
• packages/documentation/src/lib/navigation.generated.json - Navigation manifest

Related Documents

• CHANGELOG.md - Release notes process
• BAT.md - Screenshot automation with Playwright
• PROCESS.md - Development workflow