How to Comment on Documentation

The documentation site uses Hypothesis for collaborative inline annotations. Team members can highlight text on any page, leave comments, and reply to each other — all without leaving the documentation site.

Comments are anchored to the exact text you select, so feedback stays in context and is easy to find later.

Note

Hypothesis annotations are tied to the URL where they were created. The site is published to two locations:

• Production (arda-cards.github.io) — the released version, deployed when PRs merge to main. Use this for long-lived comments and discussions.
• Preview (arda-cards.github.io/documentation) — updated on every PR. Use this to leave review feedback on in-progress changes.

Annotations made on one URL are not visible on the other. Post review feedback on the preview site and lasting comments on the production site.

One-Time Setup

Create a Hypothesis account and join the team group. This takes about 3 minutes.

1. Go to hypothes.is/signup and create a free account.
   • Username: Use your GitHub username (e.g., jmpicnic) so team members can identify you.
   • Email: Any email you prefer.
   • Password: Your choice.
2. Check your email and confirm your account by clicking the verification link.
3. Log in to Hypothesis at hypothes.is/login.
4. While logged in, click this link to join the team group: hypothes.is/groups/e4e5jGAx/arda-products

You’re all set.

Leaving a Comment

1. Visit any page on the documentation site.
2. Click the small < tab on the right edge of the page to open the Hypothesis sidebar.
3. Important: Make sure the group selector near the top of the sidebar is set to arda-products, not “Public”. This keeps your comments visible only to the team. Hypothesis remembers your selection, so you only need to do this once.
4. Select any text on the page that you want to comment on. A small toolbar will appear — click Annotate.
5. Write your comment and click Post.

Tip

To leave a page-level comment that is not anchored to specific text, click the note icon (page with a +) at the top of the sidebar.

Reading and Replying to Comments

1. Open the Hypothesis sidebar (< tab on the right).
2. All annotations from team members on the current page are listed in the sidebar. Highlighted text on the page shows where comments are anchored.
3. Click Reply on any annotation to respond.

Tips

• Tags — Add tags to your annotations to categorize them (e.g., question, suggestion, typo).
• Search — Use the search box at the top of the sidebar to filter annotations by tag or keyword (e.g., tag:"question").
• Resolving discussions — When a discussion has been addressed, reply with the tag RESOLVED so the team can track which threads are done.
• Automatic cleanup — A GitHub Action periodically hides resolved annotations older than 30 days so they no longer clutter the sidebar.
• AI agent integration — AI coding agents can also read and write Hypothesis annotations via the Hypothesis MCP server. See Using Hypothesis with AI Agents for setup and workflow examples.