Skip to content

Screenshot audit — replace placeholder reuse and missing captures across docs #78

Closed as not planned

Description

@superdav42

Summary

Audit of every screenshot reference in docs/ (English source). Findings:

  • 147 image files tracked under static/img/ (admin/, config/, installation/).
  • 98 unique images are actually referenced from English docs.
  • 48 image files are orphans (exist on disk, never referenced). Several are exactly the per-step screenshots that the docs should be using but are not — they need rewiring before any new captures are taken.
  • 27 doc pages reuse the same image two or more times within a single page (a single image illustrating up to 14 different UI states). This is the primary "same screenshot used several times" pattern that needs replacing.
  • 28 addon pages under docs/addons/*/index.mdx contain zero screenshots.

The full inventory is tracked across the child issues linked below. This master issue is the place for the shared capture playbook and the cross-cutting checklist.

Worst offenders (one image used many times in one page)

Page Image Times Child issue
user-guide/payment-gateways/tax-handling.md settings-taxes.png 15× Payment Gateways
user-guide/integrations/zapier.md webhooks-list.png 14× Integrations
user-guide/configuration/creating-discount-codes.md discount-codes-list.png 14× Configuration
user-guide/integrations/zapier-register-account.md webhooks-list.png 12× Integrations
user-guide/payment-gateways/stripe.md settings-payment-gateways.png 12× Payment Gateways
user-guide/payment-gateways/getting-paid.md settings-general.png + settings-payment-gateways.png 11× + 7× Payment Gateways
user-guide/client-management/account-page.md dashboard.png 10× Client Management
user-guide/domain-mapping/how-to-configure-domain-mapping.md domains-list.png + settings-domain-mapping.png 9× + 7× Domain Mapping / Admin
user-guide/miscellaneous/sending-emails-and-broadcasts.md broadcasts-list.png + settings-emails.png 9× + 5× Domain Mapping / Admin
user-guide/integrations/webhooks.md webhooks-list.png 8× Integrations
user-guide/configuration/checkout-forms.md multiple (4 distinct images, 15 refs) 15× Configuration
user-guide/configuration/site-templates.md multiple (5 distinct, 16 refs) 16× Configuration
user-guide/configuration/customizing-your-registration-form.md multiple (3 distinct, 14 refs) 14× Configuration
user-guide/configuration/creating-your-first-subscription-product.md multiple (5 distinct, 13 refs) 13× Configuration
user-guide/client-management/upgrading-a-plan.md multiple (2 distinct, 8 refs) 8× Client Management
user-guide/client-management/canceling-a-membership.md memberships-list.png 6× Client Management
user-guide/client-management/client-websites.md customers-list.png 6× Client Management
user-guide/payment-gateways/manual-payments.md multiple (2 distinct, 6 refs) 6× Payment Gateways
user-guide/payment-gateways/paypal.md settings-payment-gateways.png 5× Payment Gateways
user-guide/configuration/the-registration-flow.md multiple (3 distinct, 9 refs) 9× Configuration
user-guide/client-management/downgrading-a-plan.md memberships-list.png 3× Client Management
Six addon pages addons-page.png 2× each Addons

Child issues

  • Integrations — zapier, zapier-register-account, webhooks
  • Payment Gateways — stripe, paypal, manual-payments, getting-paid, tax-handling
  • Configuration — checkout-forms, creating-discount-codes, customizing-your-registration-form, creating-your-first-subscription-product, site-templates, the-registration-flow, auto-search-and-replace-in-site-templates
  • Client Management — account-page, upgrading-a-plan, canceling-a-membership, downgrading-a-plan, client-websites
  • Domain Mapping, Administration & Miscellaneous — how-to-configure-domain-mapping, touring-the-admin-panel, managing-memberships, sending-emails-and-broadcasts
  • Addon docs missing screenshots — 28 addon index.mdx pages with no images
  • Rewire existing orphan screenshots — quick wins where the correct file already exists in static/img/ but the doc still references a generic one

Links to each child issue will be added in a follow-up comment.


Screenshot capture playbook

This playbook is the single source of truth referenced by every child issue. Follow it for every screenshot you take or replace.

1. Local environment

The docs are written against a local WordPress Multisite that resolves at:

http://wordpress.local:8080

Login: navigate to http://wordpress.local:8080/wp-login.php, username admin, password admin.

If wordpress.local does not resolve, add it to /etc/hosts:

127.0.0.1   wordpress.local

If a local stack is not running yet, the project ships everything you need under the Multisite Ultimate test environment (use the same admin/admin credentials whichever way you spin it up — Docker, Local, Lando, valet, etc.). Open the Network Admin dashboard (/wp-admin/network/) — every Ultimate Multisite menu lives under Network Admin → Ultimate Multisite.

2. Seed data (so screenshots are not empty)

Many of the current screenshots show empty/zero state which looks unfinished in the docs. Before capturing, make sure each list has realistic but innocuous data:

  • Customers: 6–10 with varied join dates and at least one cancelled.
  • Memberships: at least one Active, one Trialing, one On Hold, one Cancelled, one Expired.
  • Sites: 6–10 sites across two or three plans.
  • Products: at least three plans (Free, Basic, Pro) and one Package/Service.
  • Domains: two mapped custom domains, one in Ready, one in Checking DNS.
  • Payments: a mix of Completed, Pending, Refunded so the list looks real.
  • Discount codes: at least one percentage code, one fixed-amount, one expired.
  • Broadcasts: one Email broadcast, one Notice broadcast, one Draft.
  • Webhooks: one configured endpoint plus the default ones.
  • Events: leave the events log running so it has recent entries.

Use names that look generic but professional. Never use real customer data. Email addresses should be customer-N@example.com, names from a clearly fictional list (e.g. Jane Doe, Acme Designs, Beach Studio).

3. Browser and viewport

Use a clean Chrome / Chromium / Firefox profile (incognito or a dedicated profile) with:

  • No browser extensions visible (Grammarly, Honey, password manager toolbars, dev-tools panels).
  • Default zoom 100%.
  • Light mode WordPress admin colour scheme (Users → Your Profile → Color Scheme → Default).

Resize the browser window so the captured screenshot is no wider than necessary. Recommended viewports:

  • Settings / list / table pages: 1280×800 (DPR 1) or 1280×900. This is wide enough to show the WP admin sidebar plus the page content without horizontal scroll, and narrow enough that the right-hand whitespace doesn't dominate the screenshot.
  • Edit forms / modals / dialog boxes: 1024×768 is plenty; the screenshot should focus on the form, not the surrounding chrome.
  • Frontend checkout / pricing tables: 1366×900 desktop, plus a 414×900 mobile capture if the page describes mobile behaviour.

If you need a really focused capture (e.g. a single toggle, a single button), crop tightly after taking the screenshot — don't try to do it with browser-resize alone. Aim for 400–900 pixels wide for "inline" screenshots that illustrate one control.

4. Capture mechanics

Two acceptable workflows:

  1. DevTools device toolbar (Chrome Cmd+Shift+M / Ctrl+Shift+M): set "Responsive" to the viewport above, then ⋮ → Capture screenshot. This gives you pixel-exact output and excludes the OS chrome.
  2. OS screenshot tool with window selection: macOS Cmd+Shift+4 then press Space and click the window; Windows Win+Shift+S; GNOME PrtSc → Screenshot a window. Make sure no notification toasts are visible.

After capture:

  • Crop to remove dead space, but keep enough context that the reader can locate the control on the screen (the immediate breadcrumb / heading / surrounding label).
  • Annotate sparingly. If you must, use the annotation style already used in static/img/installation/multisite-wizard/ (red rounded rectangles, no shadows, no arrows pointing to obvious things).
  • Strip metadata (exiftool -all= file.png or equivalent) — no need to leak the capture machine.
  • Optimise with oxipng -o2 file.png or pngquant --quality=85-95 --speed 1 file.png. Target file size under 200 KB, ideally under 100 KB.

5. File names and placement

Existing naming convention:

  • static/img/admin/<short-name>.png — Network Admin pages and dialogs that the super admin sees (memberships-list.png, customer-edit.png, webhooks-list.png).
  • static/img/config/<short-name>.png — Settings pages and product / discount / checkout editors (settings-payments-full.png, discount-code-edit.png).
  • static/img/installation/<short-name>.png — One-time setup wizards.
  • static/img/installation/multisite-wizard/<short-name>.png — Multisite wizard sub-flow.

Keep names hyphenated, lowercase, descriptive of the screen — not the doc that uses it. Reuse the existing names when re-capturing the same screen so docs that link them don't need editing. Where the docs reference a generic placeholder, add new files with a more specific name (e.g. discount-code-edit-percentage.png, stripe-webhook-endpoint-url.png).

Several files already exist on disk but no doc references them yet — see the Rewire existing orphan screenshots issue for the list; in many cases the right fix is "wire up the existing file" before capturing anything new.

6. After replacing screenshots

  1. Run npm run build and npm run serve to inspect each affected page locally and confirm every image renders.
  2. Re-run any image-optimisation step that CI relies on.
  3. Translations under i18n/*/ may reference English filenames — the translation pipeline picks up replaced files automatically when filenames stay the same, but new filenames must be added to the relevant translated markdown. Run python3 fix-i18n-images.py (already in the repo) afterwards if any image paths change.
  4. Commit screenshots and the doc edits together so review is one diff.

7. Acceptance criteria for closing a child issue

  • Every alt-text in the affected doc has a screenshot whose content actually matches the alt-text.
  • No image appears more than once in the same page unless the page is genuinely re-referencing the same screen (rare; document the reason in the PR description if so).
  • Each new file is under 200 KB and metadata-stripped.
  • npm run build succeeds.
  • i18n/*/ builds pass (the CI workflow handles this).

Audit captured with git ls-files + a Python reference counter against docs/**/*.{md,mdx} on main.


aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.

Activity

  1. superdav42 commented on May 19, 2026

    @superdav42
    ContributorAuthor

    Child issues

    Suggested order of work:

    1. Start with Screenshots: rewire 48 orphan files under static/img (quick markdown-only wins) #85 — orphan rewire is the cheapest fix and uncovers which existing screenshots still match the current UI vs. which need recapture. It also feeds clean data into all the other issues.
    2. Then Screenshots: user-guide/integrations — replace 34 placeholder reuses (zapier, webhooks) #79–Screenshots: user-guide/domain-mapping, administration, miscellaneous — domain mapping flow, broadcasts, system emails, populated dashboards #83 in any order — these need actual new captures from wordpress.local:8080. Group captures by Network Admin area (Settings → Payments, Settings → Taxes, Domains, Broadcasts, etc.) so one session of capturing covers multiple doc pages.
    3. Then Screenshots: docs/addons — 28 addon pages with zero images need screenshots #84 — addons. New addons get one capture session each at the same time as their next feature update.

    Issue #78 stays open until all child issues are closed.


    aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.

  2. superdav42 commented on May 19, 2026

    @superdav42
    ContributorAuthor

    Cross-link: an interactive session published a parallel audit at #64 about a minute before this one (both ran from the same prompt). The two cover the same problem from different angles:

    Both bodies have the same capture playbook (1280×800, wordpress.local:8080 admin/admin, < 200 KB PNG). The findings differ only in coverage:

    • This audit additionally lists: 28 addon pages with zero screenshots, 48 orphan files in static/img/, plus heavy reuse in tax-handling.md (15×), creating-discount-codes.md (14×), zapier-register-account.md (12×), how-to-configure-domain-mapping.md (9×), sending-emails-and-broadcasts.md (9×). Screenshot audit and refresh program (master) #64 only listed those briefly under "Future work".
    • Screenshot audit and refresh program (master) #64 additionally calls out byte-identical MD5 duplicates explicitly (32 files collapsing to ~10 distinct shots) and ships a per-file remediation table per child issue.

    Suggested consolidation: keep #64 as the program tracker, fold #78's extra findings into it as new child issues for the "Future work" bullets (orphan rewire, addon docs, tax/discount/domain/email reuse), and close #79 / #80 as superseded by the narrower #65 / #66 / #67 / #74. Happy to do that on request.


    aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.

  3. superdav42 commented on May 19, 2026

    @superdav42
    ContributorAuthor

    Duplicate of #64. The two audits ran in parallel and reached the same overall finding. Net-new content from this audit has been transferred to a gap-analysis comment on #64 (#64 (comment)). Closing.


    aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions