Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Screenshot audit and refresh program (master)

Đang mở
  • Có gì không ổn?
#64 6 bình luận 0 reaction 0 người được giao Xem trên GitHub

@superdav42 đang làm issue này rồi.

Từ ngày 13/7/2026.

  • #172 của @superdav42 — đang mở

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
25/100
Loại issue
Tài liệu
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Ít trao đổi
Công nghệ
markdown
Lĩnh vực
documentation

Hướng nghiên cứu

Start with one of the linked child issues (#65–#77), then read its listed docs file and inspect the referenced images under static/img/. Follow the capture standards and run npm start to verify the documentation page; the selected child issue is done when its screenshots, references, and rendering match the documented workflow.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

documentation enhancement help wanted needs-consolidation origin:interactive origin:worker status:available

Summary

A repo-wide audit of every screenshot in static/img/ and every /img/... reference in docs/ revealed widespread problems:

  • 147 image files are tracked, but only 98 unique paths are referenced from docs/ — and many of those single paths are reused for dozens of unrelated concepts.
  • At least 32 files are byte-for-byte duplicates of each other (same MD5 hash) saved under different names.
  • At least 4 walkthroughs (Zapier, Stripe, PayPal, Customer account page) currently use a single screenshot as a placeholder for every step.

This issue tracks the program of work. Each focused area has its own child issue (linked below).

Goal

Every screenshot in the docs should:

  1. Show the actual UI being described.
  2. Be unique per concept (no recycled placeholder).
  3. Be cropped/sized to highlight the relevant control, not buried in chrome.
  4. Be reasonably small (file size + image dimensions) so the docs site stays fast.

Capture environment

The dev WordPress used to take new screenshots:

  • URL: http://wordpress.local:8080
  • Username: admin
  • Password: admin
  • Plugin: Ultimate Multisite (current main build) active on the network.

Open the login page at http://wordpress.local:8080/wp-login.php, sign in, then go to My Sites → Network Admin → Ultimate Multisite to reach every screen referenced in the docs.

If wordpress.local:8080 is not reachable from your machine, ask in the issue thread for access (a staging clone can be provided).

Capture standards

Rule Value
Browser window for screen captures 1280 × 800 (consistent across the whole doc set)
Device pixel ratio 1× (use a normal/external monitor, not a Retina-only display)
Theme WordPress default admin colour scheme, no admin-bar customisations
Browser zoom 100% — confirm with Ctrl/Cmd + 0 before each shot
File format PNG, 8-bit RGB, non-interlaced
Max longest edge 1568 px — anything larger gets auto-downscaled and wastes bytes
Min readable text height ≥ 12 px after any cropping
Crop policy Crop tightly to the panel/section being described. Do not capture the whole admin chrome unless the doc text refers to the sidebar / admin bar.
Annotations None by default. If the doc text already describes the control, the screenshot should speak for itself.
File name Keep the existing filename when replacing. For new shots, use kebab-case-area-element.png and place under static/img/admin/, static/img/config/, or static/img/installation/ to match siblings.
Optimisation Run pngquant --quality=70-90 --skip-if-larger -f -o out.png in.png (or oxipng -o 4 in.png) before committing. Target < 200 KB unless the screen genuinely needs more detail.
Recommended capture tools
  • Linux: Flameshot (flameshot gui), GNOME Screenshot, or gnome-screenshot -w for a window.
  • macOS: Cmd + Shift + 4, then space, then click the browser window. To remove window shadows: defaults write com.apple.screencapture disable-shadow -bool true.
  • Cross-platform: Playwright/Chromium headed: open http://wordpress.local:8080/wp-admin/network/admin.php?page=wp-ultimo, resize window to 1280 × 800 via the OS or DevTools device toolbar, then capture.

For full reproducibility you can drive the capture from a tiny Playwright script (1280 × 800 viewport, deviceScaleFactor 1) — useful if you’re doing many at once. Ask in this issue if you want a starter script.

Filename hygiene
  • Never paste a screenshot with macOS’s default name Screenshot 2026-… PM.png into commits — rename to the target path first.
  • On macOS, the AM/PM in the default filename contains a U+202F narrow no-break space which breaks many tools. Rename to ASCII before committing.

Audit findings

A. Exact byte-identical duplicates (same file content, different names)

These were verified with md5sum. The recycled name almost always implies a screenshot that was never actually captured.

MD5 Affected files Tracking issue
023edc1399… static/img/config/product-{custom-domains,disk-space,hide-credits,plugins,post-types,reset-limitations,site-templates,themes,upgrades}.png (9 files, all 28 236 B) #69
1dce0a089f… static/img/admin/network-dashboard-{activity-stream,first-steps,full,news,right-now,summary}.png + static/img/installation/network-dashboard.png (7 files, all 125 540 B) #70
28184a7caf… static/img/admin/settings-payments-{bottom,gateways-2,options}.png (3 files) #71
1c1ac4f60f… static/img/config/period-selection-field-{options,settings}.png (2 files) #72
74f697dd4b… static/img/installation/plugin-activated.png, static/img/installation/wizard-welcome.png #75
b9c1d601bb… static/img/admin/um-dashboard-bottom.png, static/img/admin/um-dashboard-stats.png #76

Total: 32 files that should collapse to ~10 distinct shots.

B. One screenshot reused for many concepts inside one doc (placeholder pattern)
Doc file Distinct concepts illustrated Image used Tracking issue
docs/user-guide/integrations/zapier.md 14 (Zapier dashboard, app search, trigger picker, auth modal, UM API settings, credentials, payment_received event, test step, action setup …) webhooks-list.png — wrong screen for every step #65
docs/user-guide/payment-gateways/stripe.md 13 (UM active gateways, inline card field, Checkout redirect, API keys, Stripe Dashboard, test-data toggle, Stripe webhooks, listener URL, endpoint paste …) settings-payment-gateways.png — wrong screen for most steps #66
docs/user-guide/payment-gateways/paypal.md 5 (UM active gateways, API credentials, PayPal account settings, PayPal API integration, generated credentials) settings-payment-gateways.png — wrong screen for the PayPal-side steps #67
docs/user-guide/client-management/account-page.md 16 (account menu, account overview, plan summary, Site Limits, Billing Address, update form, change template button, switch confirmation, Add Domain, DNS instructions, change password form, Danger Zone …) Recycled mix of dashboard.png, customers-list.png, domains-list.png from the network admin — but the doc is about the customer-facing subsite account page. #68
C. Cross-doc placeholder reuse (heaviest offenders)
Image Times referenced Used for Tracking issue
/img/admin/webhooks-list.png 35 Mostly Zapier walkthroughs #65, #74
/img/config/settings-payment-gateways.png 34 PayPal + Stripe walkthroughs #66, #67
/img/admin/memberships-list.png 17 Memberships list, but reused for cancel / downgrade / upgrade flows where the actual screens differ (future)
/img/config/checkout-form-step.png 16 Re-used for every field type configuration #72, #73
/img/config/settings-taxes.png 15 VAT add-on walkthrough (future)
/img/config/discount-codes-list.png 14 Multiple distinct discount-code editor screens (future)

Workflow per child issue

For each linked child issue:

  1. Open wordpress.local:8080, log in as admin / admin.
  2. Re-create / open the screen described in the doc text.
  3. Capture per the standards table above (1280×800, tight crop, < 200 KB).
  4. Save to the exact path listed in the issue (overwrite existing file — keep the filename).
  5. If the issue says "split into N shots", add the new filenames to static/img/.../ and update the markdown references in the listed docs/... file accordingly.
  6. Run npm start, visit the doc page, and confirm every shot renders and matches the surrounding text.
  7. Commit with a message like docs(screenshots): refresh <area> per issue #<N> and open a PR referencing the issue.

Child issues

  • #65 — Screenshots: Zapier integration walkthrough (14 placeholders)
  • #66 — Screenshots: Stripe payment gateway walkthrough (13 placeholders)
  • #67 — Screenshots: PayPal payment gateway walkthrough (5 placeholders)
  • #68 — Screenshots: Customer account page (16 placeholders)
  • #69 — Screenshots: Product limitation tabs (9 identical duplicates)
  • #70 — Screenshots: Network admin dashboard widgets (7 identical duplicates)
  • #71 — Screenshots: Settings → Payments tabs (3 identical duplicates)
  • #72 — Screenshots: Checkout form editor flow (heavy reuse)
  • #73 — Screenshots: Customizing the registration form (depends on #72)
  • #74 — Screenshots: Webhooks setup walkthrough
  • #75 — Screenshots: Installation wizard (1 duplicate + verify currency)
  • #76 — Screenshots: UM analytics dashboard (1 duplicate)
  • #77 — Screenshots: Site templates documentation

How this audit was done

# All tracked images
git ls-files | grep -iE '\.(png|jpg|jpeg|gif|webp)$'

# Exact-duplicate detection
find static/img -type f -name '*.png' -exec md5sum {} \; | sort | uniq -d -w 32

# Reference counts per image
grep -rohE '/img/[^)" ]+\.png' docs/ | sort | uniq -c | sort -rn

# Image dimensions / file sizes
find static/img -name '*.png' -exec file {} \;

Future work (not yet ticketed)

The audit also found heavy reuse in the following areas, which are smaller scope but still worth fixing:

  • VAT / Tax handling (tax-handling.md) — settings-taxes.png used as the VAT add-on install screenshot.
  • Discount codes (creating-discount-codes.md) — discount-codes-list.png re-used for save / active / advanced screens.
  • Domain mapping (how-to-configure-domain-mapping.md) — domains-list.png used for several different screens.
  • WooCommerce add-on (addons/woocommerce/index.mdx) — uses addons-page.png and settings-payment-gateways.png for different steps.
  • GoCardless / PayFast / Language Selector / Site Exporter / Admin Page Creator add-on docs — each has 1–2 shots that could be more specific.
  • Touring the admin panel (touring-the-admin-panel.md) — verify each linked screen still matches the current UI.

These can be ticketed as needed once the high-impact issues above are landed.

Ngôn ngữ chính
MDX
Star
0
Fork
0
Không có pull request nào được merge trong 30 ngày

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của Ultimate-Multisite/docs

Tất cả issue của Ultimate-Multisite/docs

Issue tương tự

Thêm issue về Documentation

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.