Skip to content

Conversation

@mcvinci
Copy link
Contributor

@mcvinci mcvinci commented Nov 29, 2025

This PR:

  • Integrates Tim Trevor's feedback on the following:
    • Refines API example descriptions to avoid long sentences (>30 words), and the participial phrase
    • Removes certain API limitations that shouldn't be called out at that level, using a "Limitations framework"
  • Adds some links to cross-reference component docs
  • Adds descriptions for recently added POS UI extensions examples
  • Closes https://github.com/Shopify/shopify-dev/issues/65493

Limitations framework

  • Limitations are constraints developers must work around: I only documented restrictions that require developers to handle edge cases, implement fallbacks, or design around boundaries (like size limits, availability restrictions, or failure conditions).
  • Limitations are not product descriptions: I removed statements that simply describe how the product is designed to work, its intended scope, or its normal operating requirements (like "requires hardware" or "provides read-only access").
  • Limitations highlight what can go wrong or fail: I focued on technical boundaries where operations can fail, data can be stale, or functionality is conditionally available, rather than explaining the product's standard behavior or architecture.

Tophatting

  1. In the ui-extensions repo, run yarn docs:point-of-sale 2025-10.

  2. In shopify-dev, run a server (dev server) with the templated_refs_v2_m1 feature flag enabled, and review the 2025-10 docs at https://shopify-dev.shop.dev/docs/api/pos-ui-extensions/2025-10

@mcvinci mcvinci self-assigned this Nov 29, 2025
@mcvinci mcvinci added the #gsd:47443 Templated References https://vault.shopify.io/gsd/projects/47443 label Nov 29, 2025
Fix version

Fix type error

Move subSection to original position
@mcvinci mcvinci force-pushed the refine-descriptions-limitations-links-2025-10 branch from 213826b to 00a77d5 Compare November 29, 2025 07:04
@mcvinci mcvinci force-pushed the refine-descriptions-limitations-links-2025-10 branch from c3e3ab6 to 58bf805 Compare November 29, 2025 07:16
@mcvinci mcvinci force-pushed the refine-descriptions-limitations-links-2025-10 branch from a776194 to 8a62ce3 Compare November 30, 2025 04:01
@mcvinci mcvinci marked this pull request as ready for review November 30, 2025 04:02
@github-actions
Copy link
Contributor

We detected some changes in packages/*/package.json or packages/*/src, and there are no updates in the .changeset directory. If the changes are user-facing and should cause a version bump, run yarn changeset to track your changes and include them in the next release CHANGELOG. If you are making simple updates to repo configuration, examples, or documentation, you do not need to add a changeset.

Copy link
Contributor

@timtrevor-shopify timtrevor-shopify left a comment

Choose a reason for hiding this comment

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

See 2026-01 PR for comments on limitations sections of API pages.
Approving pending resolution of those comments.

mcvinci and others added 5 commits December 2, 2025 11:01
* Update Components section to remove inappropriate content from limitations sections and add to description

* Linting

* Formatting, typos, and other minor revisions

---------

Co-authored-by: Michelle Vinci <[email protected]>
* Update Components section to remove inappropriate content from limitations sections and add to description

* Linting

* Formatting, typos, and other minor revisions

---------

Co-authored-by: Michelle Vinci <[email protected]>
@mcvinci mcvinci merged commit 4e31ea5 into 2025-10 Dec 2, 2025
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

#gsd:47443 Templated References https://vault.shopify.io/gsd/projects/47443

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants