Skip to main content

Manage Docflows

Docflows allows technical writers to review, edit, and assign automated documentation suggestions generated directly from engineering activity - either a Pull Request being opened or updated, or a Jira ticket moving to Done, Resolved, or Closed.

Automated Review, Before It Reaches Your Inbox​

Every Docflows suggestion - whether it came from a Pull Request or a Jira ticket - is generated by the same three-role process Author a Feature uses (see Doc Team Roles): an Information Architect decides which files need to change, a Technical Writer drafts them, and an Editor reviews the whole set before it ever reaches you. This all happens automatically in the background; you don't see the individual rounds the way you would on a manually-created draft. Generated files can be Markdown, reStructuredText, AsciiDoc, HTML, MDX, or DITA XML - SudoDocs matches whatever format the target file already uses (or, for a new file, whatever your existing documentation's naming convention implies).

Each suggestion card shows the outcome:

  • ✓ IA + Editor Reviewed: The Editor found no blocking issues.
  • ⚠ Editor Flagged Open Issues: The Editor and Writer went back and forth without fully resolving everything automatically - hover the badge to see what's still open, and pay closer attention to those files when you review.

A suggestion without either badge predates this review step and can be treated the same as before.

Note on the Jira path: a Jira ticket has no code diff to draft against, only its summary and description, so it's inherently the least-grounded source SudoDocs works from - give these suggestions a closer read regardless of which badge they carry.

If the Information Architect judges a change significant enough to warrant one - a new subsystem, a multi-service integration, a complex sequence of interactions - it also generates or updates a Mermaid architecture diagram for the most relevant file, fully automatically, with no action from you. This is deliberately conservative: most suggestions won't get one. Unlike Author a Feature, there's no checkbox to force a diagram here - Docflows stays fully automated end to end.

Each Docflows suggestion generated (PR or Jira-sourced) uses AI credits, same as a manually-created draft; a suggestion with an auto-generated diagram costs a little more than one without.

Triage Suggestions​

An action item appears in your inbox whenever an engineer merges (or opens/updates) a Pull Request on a connected repository, or moves a linked Jira ticket to Done, Resolved, or Closed.

  1. Open Docflows.
  2. Review the suggested target file path(s) and the AI-generated draft. A 📦 BATCH UPDATE badge means multiple files are affected - click to review each one. A card sourced from Jira shows the ticket key (e.g. PROJ-501) instead of a PR number.
  3. In the assignment panel, input the Target Release, designate an Assignee, and apply a Product Tag (e.g., Auth, API).
  4. Click Approve.

Triaged suggestions appear in the assigned Release Dashboard for final review.

Sync and Push Updates​

Writers can push approved documentation directly back to the Git repository.

  1. Open the Assigned Docflows panel in your Release Dashboard - it shows the same review badge as the Inbox.
  2. Click Review & Push on a triaged item.
  3. (Optional) Click Sync Latest Code to fetch new commits from GitHub and append missing updates to your draft. This button only appears for PR-sourced suggestions - a Jira-sourced one has no linked commits to sync from, so the option is hidden there.
  4. Select the target integration, define the file path, and click Push PR.