Skip to main content

Flow Beacon — User Documentation Specification

This specification defines the structure, content requirements, and quality bar for all public, user‑facing documentation for Flow Beacon. It is the blueprint for creating getting‑started guides, onboarding flows, feature docs, and how‑to procedures. It intentionally excludes sensitive implementation details and any secrets.

Audience for this spec: internal writers, PMs, designers, and engineers collaborating on documentation.

Scope: All user‑relevant pages and tasks surfaced in the app navigation and core flows (signup → connect platform → import scenarios → validate & govern → monitor costs and alerts).

1. Documentation Overview​

Purpose and Scope​

  • Help users quickly reach first value: connect a platform, import scenarios, validate, and resolve issues.
  • Provide clear, actionable guides for day‑to‑day tasks across Dashboard, Alerts, Costs, Blueprints, Governance, Templates, Policies, Audit, Connections, and Settings.
  • Offer troubleshooting paths and best practices without exposing internal systems, secrets, or proprietary logic.

Target Audiences and Personas​

  • Builder/Integrator: sets up and maintains automations; needs hands‑on guides and troubleshooting.
  • Ops/Platform Owner: cares about governance controls, auditability, and reliability.
  • Team Admin: manages users, connections, billing, and org settings.
  • Finance/Analyst: monitors usage and costs; exports reports.

Principles and Tone​

  • Clarity over completeness; guide the next step, link out for depth.
  • User‑centric, outcome‑oriented language (what to do, why it matters).
  • Security‑conscious: never show secrets, internal IDs, or private implementation details.
  • Inclusive, plain English; avoid jargon; explain terms on first use.

2. Content Architecture​

Top‑Level Navigation (Docs)​

  • Getting Started
  • Guides
    • By Page (Dashboard, Alerts, Costs, Blueprints, Governance, Templates, Policies, Audit, Connections, Settings)
    • By Task (Connect a platform, Import scenarios, Validate scenarios, Monitor alerts, Control costs, Manage access)
  • Integrations
    • Make.com (available)
    • Zapier (coming soon)
    • Provider accounts via secure connector
  • Troubleshooting
  • FAQ
  • Release Notes (public highlights only)

Information Hierarchy​

  • Each page/feature doc includes: Purpose → Concepts → Prerequisites → Step‑by‑step → Validation → Troubleshooting → FAQ → Related links.
  • Cross‑link related tasks (e.g., “Import Scenarios” links to “Connections” and “Blueprints”).

Cross‑Referencing & Linking​

  • Use short, descriptive link labels; avoid deep technical terms.
  • Prefer relative links within the docs site; avoid linking to private repos or internal dashboards.
  • Link screenshots or short clips only if they convey unique information; keep UI labels visible.

3. Getting Started Section Specifications​

Create a “Getting Started” series (5–8 minute path to first success):

  1. Create Your Account
  • What users need: email, password, or SSO.
  • Confirm email and sign in.
  • Success criteria: landing on Dashboard without errors.
  1. Create or Join a Workspace
  • Explain team/workspace concept at a high level (no internal IDs).
  • Invite teammates (role overview: admin, editor, viewer — keep concise).
  • Success criteria: members listed in Settings → Team/Users.
  1. Connect a Platform Account
  • Explain that Flow Beacon connects to automation platforms via a secure connector and OAuth flow.
  • Users choose a provider (e.g., Make.com) and authorize access.
  • Success criteria: connection visible in Connections with a green/active status.
  1. Import Scenarios (Blueprints)
  • From the connected platform, select scenarios to import.
  • Show how to search/filter scenarios and import one or more for validation.
  • Success criteria: scenarios appear under Blueprints and in Governance where applicable.
  1. Validate and Fix
  • Run validations on a scenario; review findings; apply suggested fixes when applicable.
  • Success criteria: validation passes with no critical issues; understand remaining warnings.
  1. Enable Monitoring
  • Where to view Alerts; how polling/refresh works from a user perspective (no internal timing specifics or APIs).
  • Configure notification preferences (if available) and review Costs.
  • Success criteria: user can see alerts stream and costs overview for the last period.

Deliverables per step

  • 3–6 concise steps with actionable verbs.
  • 1 screenshot or short clip if it reduces ambiguity.
  • “You’re done when…” success checklist.
  • Common pitfalls list with quick fixes.

4. Feature Documentation Framework​

For each page listed below, create a standalone doc using this template:

Feature Doc Template

  • Purpose: one‑sentence value statement.
  • When to use: typical scenarios and audiences.
  • Key concepts: 3–6 bullets of terms users will see in UI.
  • Prerequisites: minimal setup required.
  • How‑to tasks: ordered tasks with numbered steps (see below).
  • Validation: how users know it worked; what to expect.
  • Troubleshooting: top issues + succinct remedies.
  • FAQ: 3–8 common questions.
  • Related: links to other docs.

Common Step Patterns

  • Navigate: where the user clicks in the product.
  • Configure: fields, options, and recommended defaults.
  • Confirm: result state, success banners, or list updates.

4.1 Dashboard​

  • Purpose: overview of workspace status with quick access to key actions.
  • Tasks: interpret widgets, jump to Alerts, open recent scenarios, see quick stats.
  • Validation: widgets reflect recent activity; tiles link correctly.
  • Troubleshooting: stale data → refresh; permissions → contact admin.

4.2 Alerts​

  • Purpose: view and clear incident‑level alerts from connected platforms.
  • Concepts: severity, scenario, platform, time, selection & bulk clear.
  • Tasks: filter by severity/platform; clear selected; view details; refresh.
  • Validation: list updates after clear; counts reflect filters.
  • Troubleshooting: no alerts visible → confirm connection and recent activity; permission issues.

4.3 Costs​

  • Purpose: monitor usage and estimated costs over time.
  • Concepts: operations, transfer, billing unit; timezone display.
  • Tasks: choose time window; interpret charts; export/download if available.
  • Validation: figures match expectations on the connected platform.
  • Troubleshooting: missing data → verify connection and selected window.

4.4 Blueprints​

  • Purpose: hold imported scenarios/blueprints for validation and review.
  • Concepts: blueprint vs. scenario, versions, validation state.
  • Tasks: import from a connection; open a blueprint; run validation; review findings.
  • Validation: status badges update; last run timestamp visible.
  • Troubleshooting: import shows empty list → confirm platform team and permissions.

4.5 Governance​

  • Purpose: centralize controls, telemetry, and access.
  • Sub‑areas (adjust to what’s enabled in UI):
    • Telemetry: view scenario‑level metrics and health.
    • Scenarios: list and drill into governance metadata.
    • Data Stores: register data domains and labels.
    • Connections: see governed connections.
    • RBAC/Teams/Orgs: manage roles and membership.
    • Audit Logs: immutable record of sensitive actions.
  • Tasks: review telemetry, update a policy tag, view audit entries.
  • Validation: changes reflected across relevant pages.
  • Troubleshooting: permission denied → contact admin; data not visible → confirm connection/scope.

4.6 Templates​

  • Purpose: reusable starting points for common automations or policies.
  • Tasks: browse templates; preview; use a template; customize fields.
  • Validation: instance appears in Blueprints or Policies depending on type.

4.7 Policies​

  • Purpose: define guardrails to reduce incidents and enforce best practices.
  • Concepts: policy types, severity, scope.
  • Tasks: create a policy; set thresholds; enable/disable; view impacts.
  • Validation: policy shows active; related alerts reference policy where applicable.

4.8 Audit​

  • Purpose: inspect sensitive or administrative actions for compliance.
  • Tasks: filter by actor/date; export if available.
  • Validation: entries correspond to recent actions.

4.9 Connections​

  • Purpose: manage platform connections and provider accounts via a secure connector.
  • Tasks: add/connect account via OAuth; refresh a connection; remove/disconnect.
  • Validation: connection shows active; scenario import can see the expected accounts/teams.
  • Troubleshooting: OAuth fails → try an incognito window, ensure the correct account, verify permissions.

4.10 Settings​

  • Purpose: workspace and user preferences.
  • Tasks: update profile, notification preferences, workspace defaults, billing plan (if available).
  • Validation: preference persists after page refresh and new session.

5. User Journey Mapping​

Primary Journey: First Value​

  1. Sign up and join/create a workspace.
  2. Connect platform account.
  3. Import one scenario/blueprint.
  4. Run validation and resolve at least one finding.
  5. Observe alerts and review costs.

Milestones

  • M1: Connection linked
  • M2: First import completed
  • M3: First validation run
  • M4: First fix applied
  • M5: Alerts visible / costs reviewed

Progressive Disclosure

  • Keep the “happy path” minimal; link to Governance/Policies only after validation familiarity.
  • Surface advanced tips behind expandable sections or separate advanced guides.

Retention Touchpoints

  • Notification center highlights new platform support and helpful tips.
  • Periodic “what’s new” in Release Notes, linked from the Dashboard.

6. Content Standards and Guidelines​

Writing Style

  • Use imperative voice (“Click Connect”, “Select scenario”).
  • One idea per sentence; short paragraphs; lists over long prose.
  • Name UI elements exactly as labeled in the product.

Formatting

  • Headings: H2 for sections, H3 for tasks; avoid deep nesting.
  • Screenshots: crop to the relevant area; include alt text; blur any personal info.
  • Notes/Warnings: use callouts only when necessary.

Templates (copy and reuse)

How‑To Template

## Task Name
Purpose: what the user achieves.
Prerequisites: minimal list.
Steps:
1. …
2. …
3. …
Validation: how to confirm it worked.
Troubleshooting: 2–4 common issues + fixes.

Feature Doc Template

# Feature Name
Purpose | When to use | Key concepts
Prerequisites
Tasks (with numbered steps)
Validation | Troubleshooting | FAQ | Related

Integration Guide Template

# Integrate with <Provider>
Overview and prerequisites (provider account, permissions)
Connect account (OAuth steps)
Select team/workspace (if prompted)
Import scenarios/objects as applicable
Validation and common errors

Maintenance

  • Update docs alongside feature flags and releases.
  • Replace screenshots when labels or layout change meaningfully.
  • Use semantic commit messages for doc changes.

7. Quality Assurance Framework​

Reviews

  • Writer self‑review (clarity, accuracy against UI).
  • PM/Design review (terminology, alignment to flows).
  • Engineering spot‑check (no sensitive details exposed).

User Testing

  • Define 3 tasks per milestone (e.g., connect, import, validate) and test with new users.
  • Record success rate, time to complete, and blockers; fold feedback into docs.

Feedback Channels

  • “Was this helpful?” link to a short form.
  • Docs repo issues with labels: docs-bug, docs-request, docs-question.

Metrics

  • Time to first success (TTFS) from Getting Started.
  • Search queries with zero results; top exit pages.
  • Bounce rate and average time on task pages.

8. Page‑to‑Doc Mapping (Authoring Backlog)​

Create or update the following docs using the templates above. Prioritize in this order:

  1. Getting Started overview and quickstart path
  2. Connections (link account via OAuth; manage connections)
  3. Import Scenarios (Blueprints)
  4. Validate and Fix (Blueprints → Validation results)
  5. Alerts (view, filter, clear)
  6. Costs (interpret metrics)
  7. Governance (Telemetry, Scenarios, Data Stores, Connections, RBAC, Audit Logs)
  8. Templates
  9. Policies
  10. Audit
  11. Settings (profile, preferences, team, billing if applicable)

Optional/advanced (as features are confirmed in UI): Teams, Pricing, Uploaded Blueprints analysis, Test Blueprints, Generate.

9. Accessibility and Internationalization​

  • Alt text on every image; avoid text embedded in images.
  • Ensure contrast and legible font sizes in screenshots.
  • Use consistent date/time formats; specify timezone when relevant.
  • English first; plan for future localization by keeping strings concise.

10. Implementation Notes for This Docs Site​

  • Organize files under:
    • docs/getting-started/*
    • docs/guides/*
    • docs/features/*
    • docs/integrations/*
    • docs/troubleshooting/*
    • docs/specs/* (this document)
  • Name screenshots descriptively and store in static/img/screenshots/<area>/<name>.png.
  • Keep public links and examples generic; never include secrets, keys, or internal hostnames.

11. Glossary (User‑Facing)​

  • Scenario/Blueprint: an automation configuration imported from a provider.
  • Connection: a linked provider account authorized to share data with Flow Beacon.
  • Validation: checks that identify issues and best‑practice gaps in a scenario/blueprint.
  • Alert: a time‑stamped notification indicating an issue or noteworthy event.
  • Policy: a rule that enforces a best practice or limit.

12. Next Steps Checklist​

  • Stand up “Getting Started” pages based on Section 3.
  • Write Connections, Import Scenarios, and Validate guides first.
  • Add Make.com integration guide; mark Zapier as “coming soon”.
  • Capture screenshots for each step with blurred personal data.
  • Add a lightweight feedback link to each page.