Skip to content

docs(factories): screenshots and content polish - #579

Merged
rachaelrenk merged 15 commits into
mainfrom
rrenk/factories-screenshots
Aug 19, 2026
Merged

docs(factories): screenshots and content polish#579
rachaelrenk merged 15 commits into
mainfrom
rrenk/factories-screenshots

Conversation

@rachaelrenk

@rachaelrenk rachaelrenk commented Aug 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Ongoing home for Warp Factories doc polish found while continuing the post-launch review: product screenshots and content fixes. More of both will land here as they're found.

Changes

factories/index.mdx

  • Added a diagram of the software factory concept loop (triage, spec, implement, review, verify, ship, monitor, with human review checkpoints) to the "What is a software factory?" section. Later replaced with a cleaner, higher-resolution source of the same diagram.
  • Reworked the section's opening line to avoid duplicating the page intro.
  • Reworked the "Who benefits from Warp Factories" list: replaced bolded-term definitions with plain sentence descriptions, and reworded the intro sentence.

factories/factory-dashboard.mdx

  • Added a screenshot of the Activity page (work items grouped by stage: Triage, Planning, Building, Reviewing) to the "Track work items on Activity" section. Later replaced with a cleaner, higher-resolution source of the same screenshot.
  • Added a second Activity screenshot showing the Stage filter chip and search bar, illustrating the existing "Created by"/"Stage" filtering paragraph.
  • Added a screenshot to "Read metrics on the Dashboard page" showing the Cost per PR chart (broken down by compute/platform/inference cost) alongside two example Scorer cards.

factories/quickstart.mdx

  • Changed "10 minutes" framing to "less than 10 minutes" in the frontmatter description and intro sentence.
  • Added the Slack thread-reply screenshot to "Send your first work item" as an example of following progress from Slack.
  • Removed the "Otherwise," transition from the note back to prose in "Set up your factory."
  • Shortened the Foreman name sentence in step 4.
  • Split steps 5 and 7 into two sentences each so the optional connect-later path reads as its own sentence, with a link to Connect your factory.
  • Reworded the "Send your first work item" intro's opening sentence.

factories/connect-your-factory.mdx

  • Removed the "Integration guides" section, which duplicated the same 5 sources, links, and one-liners already in the "Choose a source" table.
  • Simplified the Linear/Jira exclusivity sentence in "Choose a source," including a follow-up wording tweak ("at once" -> "at the same time") from review.
  • Replaced the vague 4-step "Connect a source" numbered procedure with two short paragraphs covering what it actually needs to convey: default automations/filters and testing the connection.
  • Reworded the automation-start sentence in "How work reaches your factory."
  • Tightened the paragraph describing the foreman/work-item flow, removing detail already covered by how-factories-work.mdx and linking there instead.
  • Reworked the Factory MCP paragraph to remove a colon and an em dash.
  • Rewrote the direct-run bullet in "Direct runs and schedules" with concrete steps (click New on the Runs page, describe the task to the foreman) instead of vague framing.
  • Dropped the closing "Next, customize which agents..." line, which pointed to Definitions as code, a page that sits earlier than this one in the sidebar.

factories/integrations/slack.mdx

  • Added a screenshot of the factory's Slack app replying with progress updates in a channel thread (cropped from the original capture to remove the requester's name/photo).
  • Wording tweaks: "send it work" -> "send work"; "app, carrying the factory's name and avatar" -> "app with the factory's name and avatar"; shortened the first prerequisite bullet.
  • Reordered sections to match the GitHub/GitLab/Linear/Jira integration guides: converted "Connect the factory" from prose to a numbered procedure, moved "Configure factory automations for Slack" to immediately follow it, and moved "Who can start work" next to "Follow work and review outputs," right before Troubleshooting.
  • Replaced the "Start and continue work from Slack" table with prose, per review feedback that the table's Context/Slack output columns mostly restated the obvious and repeated the same phrasing across rows without adding information beyond the surrounding text.

factories/integrations/github.mdx, factories/integrations/jira.mdx, factories/integrations/linear.mdx

  • Applied the same wording fixes found during the Slack review: removed em dashes in github.mdx (Permissions, "How the factory responds") and jira.mdx (Connect Jira step 3), and fixed an awkward "send it issues" construction in linear.mdx's intro.

All of the new images are sourced from launch materials and cropped to remove Figma export artifacts. They're interim assets, to be swapped for live product screenshots once a demo factory has real usage history to capture.

Follow-ups (not blocking this PR)

  • Real/sample factory-as-code example repo for enterprises - needs an engineer to stand up.
  • Replace the interim screenshots above with real product screenshots once available.
  • gitlab.mdx still has an unresolved OPEN QUESTION for tech review (PR #549) comment about whether GitLab is supported as a definition host - already surfaced to the team, pending their verification.

Unverified claims

None - this PR only adds screenshots/diagrams and edits supporting prose; no new UI labels, flags, or claims were introduced.

Co-Authored-By: Warp agent@warp.dev

@rachaelrenk @warp-agent
docs(factories): add Slack thread-reply screenshot to slack.mdx
5e5ffe1 
Shows the factory's Slack app posting progress updates in the thread
where work started, per stakeholder feedback requesting a product
shot for the Slack integration page. Cropped to remove the requester's
name/photo from the original capture.

Co-Authored-By: Warp <agent@warp.dev>
@cla-bot cla-bot Bot added the cla-signed label Aug 19, 2026
@vercel

vercel Bot commented Aug 19, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs Ready Ready Preview Aug 19, 2026 11:44pm

Request Review

@warp-for-oss

warp-for-oss Bot commented Aug 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

warp-for-oss[bot]
warp-for-oss Bot reviewed Aug 19, 2026
View reviewed changes

@warp-for-oss warp-for-oss Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overview

This PR adds a single Slack thread screenshot figure to the factory Slack integration page, placing it next to the prose that explains where factory progress updates appear. The added alt text, caption, asset path, and standard screenshot width are consistent with the docs style guidance.

Concerns

No blocking concerns found. The diff adds no tests or executable code; the security pass found no security issues in the changed prose or asset reference.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

@rachaelrenk rachaelrenk self-assigned this Aug 19, 2026
@rachaelrenk @warp-agent
docs(factories): add software factory diagram and Activity page scree…
2df3065 
…nshot

- Add the software factory concept-loop diagram (from the launch blog) to
  index.mdx's 'What is a software factory?' section, cropped to remove
  Figma export artifacts.
- Add a real Activity page screenshot (from the launch blog) to
  factory-dashboard.mdx's 'Track work items on Activity' section, cropped
  to remove the Figma canvas margin and a corner marker artifact.
- Both are interim assets sourced from launch marketing materials, to be
  replaced with live product screenshots once a demo factory has real
  usage history.

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk @warp-agent
docs(factories): rework Who benefits from Warp Factories bullets
ce536d4 
- Replace bolded-term + dash definitions with plain sentence descriptions,
  since these items aren't discrete terms/features being defined.
- Rework the intro sentence and its lead-in to the list.

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk @warp-agent
docs(factories): quickstart tweaks
ac9d2a6 
- Change '10 minutes' framing to 'less than 10 minutes' in the frontmatter
  description and intro sentence.
- Add the Slack thread-reply screenshot to 'Send your first work item' as
  an example of following progress from Slack.

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk @warp-agent
docs(factories): polish quickstart setup steps
2cce73d 
- Remove the awkward 'Otherwise,' transition from the note back to prose
  in 'Set up your factory'.
- Shorten the Foreman name sentence in step 4.
- Split steps 5 and 7 into two sentences each so the optional
  connect-later path reads as its own sentence, with a link to connect
  your factory.
- Reword the 'Send your first work item' intro's opening sentence.

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk @warp-agent
docs(factories): trim duplication and vagueness in connect-your-factory
b4cea92 
- Remove the 'Integration guides' section, which duplicated the same 5
  sources, links, and one-liners already in the 'Choose a source' table.
- Simplify the Linear/Jira exclusivity sentence in 'Choose a source'.
- Replace the vague 4-step 'Connect a source' numbered procedure (pick a
  factory, install the integration) with two short paragraphs covering
  the two things it actually needs to convey: default automations/filters
  and testing the connection.
- Reword the automation-start sentence in 'How work reaches your factory'.
- Tighten the wall-of-text paragraph describing the foreman/work-item
  flow, removing detail that's already covered by how-factories-work.mdx
  and linking there instead.

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk @warp-agent
docs(factories): clean up Factory MCP and Direct runs and schedules
f143562 
- Rework the Factory MCP paragraph to remove the colon and em dash.
- Rewrite the direct-run bullet with concrete steps (click New on the
  Runs page, describe the task to the foreman) instead of vague framing,
  and remove its colon.
- Drop the closing 'Next, customize which agents...' line: it pointed to
  Definitions as code, which sits earlier than this page in the sidebar,
  making it read as a disembodied non-sequitur rather than a next step.

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk @warp-agent
docs(factories): wording tweaks in Slack integration guide
eb39f11 
- 'send it work' -> 'send work'
- 'app, carrying the factory's name and avatar' -> 'app with the factory's
  name and avatar'
- Shorten the first prerequisite bullet

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk @warp-agent
docs(factories): reorder Slack guide to match sibling integration docs
3f4e442 
- Convert 'Connect the factory' from prose to a numbered procedure,
  matching the GitHub/GitLab/Linear/Jira pattern.
- Move 'Configure factory automations for Slack' to immediately follow
  the connect steps, instead of being stranded after two usage/reference
  sections.
- Move 'Who can start work' down next to 'Follow work and review
  outputs', right before Troubleshooting, mirroring where sibling docs
  place their Permissions section.

New order: Prerequisites -> Connect the factory -> Configure automations
-> Start and continue work (reference) -> Follow work and review outputs
-> Who can start work -> Troubleshooting and reconnection -> Privacy.

Co-Authored-By: Warp <agent@warp.dev>
rachaelrenk
rachaelrenk commented Aug 19, 2026
View reviewed changes
Comment thread src/content/docs/factories/connect-your-factory.mdx Outdated
@rachaelrenk @warp-agent
docs(factories): apply Slack-review wording fixes to sibling integrat…
10c7fbb 
…ions

- linear.mdx: 'send it issues' -> 'send issues' in the intro, matching
  the same fix applied to slack.mdx.
- github.mdx: remove two em dashes in the Permissions and 'How the
  factory responds' sections.
- jira.mdx: remove an em dash in the Connect Jira step 3 automation note.

Structural review of github.mdx, gitlab.mdx, linear.mdx, and jira.mdx
against the same criteria used for slack.mdx found no ordering issues --
these four already follow the setup -> configure -> reference ->
permissions -> troubleshooting pattern that slack.mdx was reordered to
match.

Co-Authored-By: Warp <agent@warp.dev>
hongyi-chen
hongyi-chen reviewed Aug 19, 2026
View reviewed changes
Comment thread src/content/docs/factories/integrations/slack.mdx

A single Slack message can match more than one automation. For example, if one automation triggers on **App mentioned** and another triggers on **Message posted in channel** in the same channel, a channel message that mentions the app starts two separate runs, one for each automation. To avoid duplicate runs, don't point both triggers at the same channel.

## Start and continue work from Slack

@hongyi-chen hongyi-chen Aug 19, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure if this table is fully necessary, im not sure if the context / slack output is overexplaining it

@rachaelrenk rachaelrenk Aug 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call, the table wasn't earning its space. Replaced it with prose that keeps only the genuinely useful distinctions (mention/DM starts work, a reply only continues an existing work item, automations can start work without a mention) and cut the repeated context/output framing.

@rachaelrenk @warp-agent
docs(factories): drop redundant table in slack.mdx per review feedback
2347122 
Hong Yi flagged the 'Start and continue work from Slack' table as
possibly unnecessary and over-explaining. The Context/Slack output
columns mostly restated the obvious (of course the triggering message
is context) and repeated the same acknowledgment/progress-updates
phrase in nearly every row, without adding info beyond what the intro
paragraph and the following sentence already said. Replaced the table
with tight prose that keeps only the genuinely distinguishing facts:
mention/DM starts work, a reply only continues existing work, and
automations can start work without a mention.

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk @warp-agent
docs(factories): upgrade concept diagram and Activity screenshots
168d43d 
- Replace factories-concept-loop.png and factory-dashboard-activity.png
  with clean, higher-resolution source exports of the same designs
  (found via Figma), instead of the cropped launch-blog versions.
- Add factory-dashboard-activity-filters.png showing the Stage filter
  chip and search bar, illustrating the Created by/Stage filtering
  paragraph in factory-dashboard.mdx. Redacted the source screenshot's
  visible requester name while preserving the Stage filter chip.

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk @warp-agent
docs(factories): add Dashboard metrics and Slack automation screenshots
eb88c86 
- Replace factory-dashboard-activity.png with an even cleaner, higher-
  resolution source that shows fuller (though still slightly clipped)
  relative timestamps.
- Add factory-dashboard-metrics.png (Cost per PR chart broken down by
  compute/platform/inference, plus example Scorer cards) to the
  'Read metrics on the Dashboard page' section of factory-dashboard.mdx.
  Anchoring the previously-approved Code Quality/Efficiency cards next
  to the documented Cost per PR metric reads naturally as example
  Scorer cards, which the surrounding text already describes.
- Add slack-automation-example.png to slack.mdx, illustrating the
  acknowledgment -> progress update -> tracked task pattern described
  in 'Start and continue work from Slack'.

All three sourced from user-provided launch assets, cropped to remove
Figma export corner markers.

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk @warp-agent
docs(factories): remove redundant Slack automation screenshot
a534d40 
The new example duplicated the visual pattern already shown by
slack-factory-thread-reply.png in 'Follow work and review outputs'
(bot replying in a thread with acknowledgment/progress/links), adding
no new information.

Co-Authored-By: Warp <agent@warp.dev>
@rachaelrenk
rachaelrenk merged commit eee9682 into main Aug 19, 2026
8 checks passed
@rachaelrenk
rachaelrenk deleted the rrenk/factories-screenshots branch August 19, 2026 23:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@warp-for-oss warp-for-oss[bot] warp-for-oss[bot] left review comments
@hongyi-chen hongyi-chen hongyi-chen approved these changes

Assignees

@rachaelrenk rachaelrenk

Labels

cla-signed

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@rachaelrenk @hongyi-chen