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. These are SudoDocs' built-in roles, not people on your team. This all happens automatically in the background; open Review history on the card to see each round - the Information Architect's plan, the Writer's drafts and revisions, and the Editor's comments - and earlier versions. 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. Open The Editor's open issues on the card to see what's still open, and pay closer attention to those files when you review - or use Request changes. These suggestions also show under Needs attention on the dashboards.

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 draft. Each card's left side has the pull request (or the Jira ticket key, such as PROJ-501), the target file(s), and under Proposed changes the list of files with lines added and removed, how many you've reviewed, and Split / Unified. Click a file to jump to it; its changes fill the rest of the card. A 📦 BATCH UPDATE badge means several files are affected. The approval panel comes right after the file list and stays in view while you scroll through the changes. On a narrower screen the file list and approval panel sit above the changes. Show or hide the changes collapses them.
  3. In the assignment panel, pick the Target Release - or choose + New release... and type its name to create it when you approve - and choose an Assignee.
  4. Under Release notes, choose Include or Not needed - you can't approve without choosing. SudoDocs pre-selects its suggestion ("Suggested by SudoDocs"), for example Not needed for a typo fix. For Include, check the section (New Features, Enhancements, Bug Fixes, Known Issues or Developer Release Notes), the product category (from your Product Categories, or Other) and the line for the release notes.
  5. Click Approve. An included suggestion joins the release's release notes queue; it moves with the suggestion if you change its release, and leaves the queue if you switch to Not needed or dismiss it. The card shows Release notes: queued, in draft or not needed.

Approved suggestions appear on the release's Release Dashboard, under its Docflows button, for final review and pushing - see Review and Push Docflows. The assignee sees them under Assigned to you and in Your work on their Workspace.

If the engineer keeps pushing to the pull request, the card shows New commits since this draft. SudoDocs doesn't redraft a suggestion you may already be working on; click Sync Latest Code (next to Proposed changes) to add what the draft is missing - you don't have to approve it first, and your edits are kept. See Manage Engineering Changes.

Request Changes​

When a suggestion needs more than a quick edit, tell SudoDocs what to change:

  1. On the card, open Request changes.
  2. Describe the change, for example "Mention that the default region is us-east-1". If the suggestion has several files, choose one, or leave All files.
  3. Click Revise (8 credits).

SudoDocs' Technical Writer makes the change, following your Doc Team Roles instructions and style guide, and its Editor reviews the result, with one more pass if it finds a blocking issue. Images aren't changed. The card's badge and Review history are updated, and the history shows who asked for what.

Earlier Versions​

Review history keeps the text of each version: every draft and revision, and what was there before each request. Click View this version under a round to read it, and Restore this version to put it back - what's there now is kept as a version too, so you can undo it. The latest five versions are kept; older rounds keep their comments.

When a Repository Needs a Sync​

SudoDocs drafts suggestions from its own copy of your repositories. When your docs repository has changed since SudoDocs last read it, Docflows and the Release Dashboard show a notice such as acme/docs is 12 commits behind GitHub. Click Let admins know to email your organization's admins (once a day per repository), or Hide to hide it for the day. Admins see Sync now instead. See Keep in Sync.

Is a Suggestion Still Needed?​

Suggestions can wait a while, and in the meantime your docs move on - a writer may even have made the same change by hand. Check against your docs compares a suggestion with your documentation repository as it is today:

  • Your docs already have these changes: use Dismiss as done.
  • Your docs probably already have these changes, in other words: SudoDocs read both versions and believes your docs already say it differently - each file shows the reason. Check them, then use Dismiss as done. These are never dismissed in bulk.
  • Still needed: your docs haven't changed since this was drafted.
  • Still needed. Your docs changed since; the suggestion was updated to fit them: SudoDocs moved the suggestion onto the newer version of each file, so pushing it won't undo anyone's later work.
  • Some files are already in your docs; the rest are still needed.
  • Your docs changed in the same places: review the flagged files before you push. SudoDocs leaves those files as they were.
  • Some files this suggestion updates aren't in your docs any more.

The result lists each file, with when it was checked.

Comparing the text is free. When your docs changed since the suggestion was written, the lines no longer match exactly, so SudoDocs also reads both versions to see whether your docs already say the same thing in other words - the file is then marked already in your docs (in other words), with the reason, and the suggestion is probably in your docs. That costs 1 credit for each suggestion that needs it, and is skipped (text check only) if you're out of credits.

When you push a suggestion, files the check found already in your docs are left out - the push dialog lists them, and Push them anyway includes them.

  • Check all against your docs at the top of the page checks every suggestion. When some are already in your docs, Dismiss N already in your docs as done dismisses them all; each is checked once more first.
  • Suggestions older than three days are checked automatically when you open Docflows, at most once a day. The automatic check compares text only, so it's always free. The page doesn't reload under you - click Show the results when you're ready.
  • The card also shows whether the engineering pull request was merged or closed, not merged, with the date. A closed one may never ship, so check before you spend time on it - an approved suggestion whose pull request closed also offers Dismiss.
  • The release's Docflows list (on its Release Dashboard) shows the same badges, with Check all against your docs for that release.

Dismiss as done sets the suggestion's status to Done and removes it from Docflows. Unlike Dismiss (status Rejected), its release-notes entry stays in the release's queue, since the change still ships in that release.

Which Version of Your Docs Is Checked​

  • The live files, not the last sync. SudoDocs reads each file straight from GitHub when you check, so you don't need to sync the repository first. (Syncing still matters for drafting: a suggestion is written against the copy of your docs from the last sync. If that copy was out of date, the check moves the suggestion onto the current files, or flags the files that conflict.)
  • Your docs branch. SudoDocs reads your docs repository's Docs branch if your admin set one, otherwise its default branch on GitHub - usually main. That's the same branch Docflows opens its pull requests against, so the check compares against exactly what pushing would change.
  • Merged changes only. Edits still waiting in an open, unmerged docs pull request aren't in the default branch yet, so they don't count as "already in your docs".
  • Another working branch? If your team writes docs on a different branch (for example develop), ask an admin to set it as the repository's Docs branch; checks, pushes and syncing then all use it.
  • Who can check. Anyone on the doc team - Writers and System Administrators - can check suggestions, check them all, and dismiss them as done. An administrator only has to connect the documentation repository once. Until one is connected, the check buttons don't appear. If you connect more than one, SudoDocs checks against the first.

Screenshots in a Suggestion​

When your administrator has set up screenshots for Docflows, each suggestion's card has a Screenshots list:

  • SudoDocs reads the pull request and picks the pages a reader would need to see, with the reason for each ("The PR adds a Refund button to the customer page") and how sure it is. Pages it's confident about are taken right away (✓); the rest wait for you, unticked.
  • If an existing screenshot in your docs is now out of date, the list says Replaces that image - the new screenshot updates it in place, so every page that uses it gets the new one.
  • To take more, tick pages in the list, or type or pick any page of your app in Add a page, then click Take selected screenshots.

A screenshot taken after the draft was written isn't used in any file yet. In the review, choose the file under the image and click Insert into file - SudoDocs adds the image with the right syntax and path for that page. Planning a pull request's screenshots costs 2 credits; each screenshot's personal-data check costs 1.

Sync and Push Updates​

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

  1. Open the release's Release Dashboard and click its Docflows button (for example Docflows: 2 for you) - the list shows the same review badge as the Inbox. See Review and Push Docflows.
  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. Review each file's changes - before and after, side by side or in one column - edit where needed, and tick Reviewed. See Review & Push.
  5. Select the target integration and click Push PR.