Skip to main content

Milestone 18: Customer-facing documentation (inboxops-docs)

Purpose: Provide public documentation for InboxOps at docs.inboxops.app, built with Docusaurus from the inboxops-docs repository. Content is Markdown; audience is customers, integrators, and API users.

Exit state: inboxops-docs repo contains a Docusaurus site; content covers getting started, core concepts, and API/features; site is deployable to docs.inboxops.app.

Spec reference: §2.8 Public API (for API docs), §2.13 Marketing (for audience context). Customer docs are separate from PRODUCT-AND-ARCHITECTURE.md (internal) and from the implementation plan.

Prerequisites: M16 (Polish) or M17; product is stable enough to document. Can start earlier with stubs and update as features ship.

Repository: inboxops-docs (in this workspace). URL: docs.inboxops.app. Tech: Docusaurus. Content: Markdown.

18.1 Docusaurus setup (inboxops-docs)​

Tasks​

  1. Initialize Docusaurus

    • In inboxops-docs: create Docusaurus project (e.g. npx create-docusaurus@latest . classic or website + docs structure). Use TypeScript if desired; keep config minimal for Markdown-only docs.
    • Configure docusaurus.config.js: title "InboxOps Documentation", baseUrl for docs.inboxops.app, organization/repo if applicable, theme options.

  2. Site structure

    • docs/ — all customer-facing docs as Markdown (.md or .mdx). Use sidebars for nav (e.g. Introduction, Getting started, Guides, API reference, Changelog).
    • Optional: src/pages/ for landing (index) or redirect to docs. Ensure docs.inboxops.app resolves to the docs section or a clear entry point.

  3. Build and deploy

    • Local: npm run start (or yarn start) serves site; npm run build produces static output. Document deploy target (e.g. Vercel, Netlify, or custom host) for docs.inboxops.app. CI (e.g. GitHub Actions) can build and deploy on push to main.

Acceptance criteria​

CriterionStatus
inboxops-docs builds with Docusaurus; no errors on build and start.Pending
Site is configurable for docs.inboxops.app (baseUrl, favicon, title).Pending
Deploy path to docs.inboxops.app documented or automated.Pending

18.2 Core documentation content (Markdown)​

Tasks​

  1. Introduction

    • docs/intro.md (or index): What InboxOps is, who it’s for, link to signup and pricing. Short and welcoming.

  2. Getting started

    • Account and workspace: sign up, first login, workspace (tenant) concept.
    • First inbox: connect an inbox (IMAP, Gmail, Microsoft) — high-level steps; link to detailed guides if needed.
    • First ticket: how email becomes a ticket, how to reply. Optional: invite a team member.
    • All content in Markdown; use Docusaurus admonitions, code blocks, and links.

  3. Guides (as needed)

    • Connecting inboxes: IMAP, Gmail, Microsoft; connection status and reconnect.
    • Managing tickets: list, filters, reply, internal notes, tags, assignee.
    • Team and roles: invite, roles (Admin, Agent, Viewer), settings.
    • Billing and plans: trial, plans, upgrading, locked state.
    • Webhooks and API: overview of webhooks and Public API; link to API reference. No outbound reply via API (state clearly).
    • SLA and business hours (if documented for customers).
    • Content aligned with product behaviour from PRODUCT-AND-ARCHITECTURE; no internal-only details (e.g. RLS, implementation plan).

  4. API reference

    • Public API: base URL, authentication (Bearer API key), rate limits, error format. List endpoints (tickets, messages, inboxes, tags) with method, path, query/body, and example responses. Can be hand-written Markdown or generated from OpenAPI (M14); if generated, document how to refresh. Section 2.8 as source of truth.
    • Webhooks: events, payload envelope, signature verification, retries. Section 2.8.

  5. Other

    • Changelog or release notes (optional): new features and fixes; can be a single doc or per-version.
    • FAQ (optional): common questions (billing, limits, security, data residency).
    • Legal or trust: link to main site legal pages (terms, privacy); no duplicate legal text here unless required.

Acceptance criteria​

CriterionStatus
Intro and getting started are clear and accurate; a new user can follow them.Pending
At least one guide per major area (inboxes, tickets, team, billing, API/webhooks) or a single “Guides” section covering these.Pending
API reference matches Public API (Section 2.8); auth and limits documented; “no outbound reply via API” stated.Pending
All content is Markdown in inboxops-docs; sidebars and nav make it easy to find topics.Pending

18.3 Quality and maintenance​

Tasks​

  1. Review and ownership

    • Docs are reviewed for accuracy against the current product (and PRODUCT-AND-ARCHITECTURE where relevant). Assign owner or process for doc updates when features change (e.g. after each milestone or release).

  2. Links and versioning

    • Internal links work (Docusaurus relative paths). External links: app (inboxops.app), signup, pricing, legal. Optional: versioned docs (Docusaurus versioning) if you support multiple product versions.

  3. Search and UX

    • Docusaurus search (default or Algolia) works so users can find topics. Mobile-friendly; readable typography and contrast.

Acceptance criteria​

CriterionStatus
Process or owner for keeping docs in sync with product is documented or assigned.Pending
No broken internal links; external links point to correct app/marketing URLs.Pending
Search works; site is usable on mobile.Pending

Milestone 18 sign-off​

CriterionStatus
All tasks in 18.1–18.3 complete.Pending
Docusaurus site in inboxops-docs builds and is deployable to docs.inboxops.app.Pending
Core docs (intro, getting started, guides, API reference) are in Markdown and accurate.Pending
E2E (optional): Docs site build and key pages load (see INDEX — Testing strategy).Pending
Maintenance and review process is clear.Pending
Customer-facing documentation milestone complete.Pending