DocFlow

dashboard
accepted
editor

Inspiration

We were tired of “docs later” turning into “docs never.” Shipping fast meant our CHANGELOG.md got patchy, Confluence drifted, and onboarding slowed. We wanted a system that listens to real dev activity (PRs, commits, JIRA) and produces useful, to-the-point docs without turning every minor tweak into noise.

What it does

DocFlow turns PR merges into two outcomes: Append-only changelog: Every merge becomes a clean, auditable entry (never rewritten). Selective docs updates: Only user-impacting changes (new endpoints, parameters, config, CLI flags, core logic updates) generate or revise Markdown in docs/. Trivial UI/layout edits are ignored. It also posts Slack notifications, stores a tamper-evident history in DynamoDB, and can sync repo docs to Confluence as the source of truth. Reverts are recorded as new changelog entries (no deletions).

How we built it

Runtime: Node.js + Express webhook server. Integrations: GitHub API (PRs, diffs, content), JIRA API (context), Slack Webhooks (pings). LLM: Google Gemini for concise, house-style docs (prompted with PR title/body, commits, diff, and existing docs snippets to avoid repetition). Data layer: AWS DynamoDB with transactional records: PAIR: PR diff hash + rendered changelog hash. DOC_ONLY: Docs-only pushes with commit/diff hash. Docs-worthiness: Lightweight diff heuristics + LLM guidance determine whether to touch docs/.

Challenges we ran into

Signal vs noise: Detecting when a change deserves documentation without spamming. Idempotency & safety: Ensuring append-only behavior and no destructive edits. LLM grounding: Preventing repetition by feeding existing docs snippets and strict output JSON. GitHub content race conditions: Safely upserting files on main across rapid merges.

Accomplishments that we're proud of

Append-only, auditable history with clean reverts that never erase context. Docs that stay current without documenting the trivial. Zero-touch Slack notifications that summarize what changed and which docs were updated. Built a full-stack end to end dev tool.

What we learned

Small, deterministic heuristics + LLMs beat LLMs alone. Tight prompts with explicit “do/don’t” rules drastically improve doc quality. Append-only logs make rollback stories simple and trustworthy.

What's next for DocFlow

Deeper Confluence sync: Section-level updates with backlinks to PRs. Richer API diffs: Structured OpenAPI/GraphQL schema comparison. Reviewer workflows: Slack buttons to accept/tweak generated docs. Quality scoring: A simple thresholding model for docs-worthiness: