# How to Write a Comparison Page Brief for a Developer

> Get a ready‑to‑ship one‑page comparison brief with schema, headings and citation‑ready claims that a developer can implement in a single sprint.

Source: https://comppound.com/blog/how-to-write-a-comparison-page-brief-for-a-developer (published 2026-10-28)

Say you run a 12‑person SaaS that needs a clean “Feature A vs Feature B” page to help prospects decide, and you have only a day to hand it off to a developer. This guide shows exactly what to include in the brief, the order to assemble it, and how to verify it’s ready for code.

## What the final brief looks like
A one‑page document containing:
A JSON‑LD schema block that marks up the comparison table.

A clear heading hierarchy (H2 for each product, H3 for each attribute).

Three to five bullet‑style claim statements, each backed by a verifiable source you can link to.

A short “Why choose us” paragraph that can be reused in meta description.

You’ll need access to your product data sheet, a list of reputable sources for each claim, and a simple text editor.

## Step‑by‑step assembly

1. **Gather the core data** – Open your product spec spreadsheet and copy the top five attributes you want to compare (e.g., pricing, integration, security, support, SLA). For each attribute, note the exact figures or statements that differentiate the two options.
   *How to know it worked:* you can list the values side‑by‑side in a temporary table and see no empty cells.

2. **Write the heading structure** – Start the document with an H2 that names the comparison (e.g., “Feature A vs Feature B”). Under that, add an H3 for each attribute name. Keep the wording identical for both sides so the table reads naturally.
   *Check:* run a quick find‑replace to ensure every H3 appears exactly twice.

3. **Create claim statements** – For each attribute, draft a one‑sentence claim that highlights the advantage of the winning side. Append a citation link in parentheses. Use only sources you can verify (product datasheet, third‑party review, industry report).
   *Verify:* click each link; it should load a page that contains the exact figure or quote you referenced.

4. **Add JSON‑LD schema** – Insert a `` block at the top of the page. Use the “ProductComparison” type, list the two products, and map each attribute to the “featureComparison” property. Fill in the name, URL, and description fields with the text you just wrote.
   *Test:* run the page through Google’s Rich Results Test and look for a “ProductComparison” result without errors.

5. **Finalize the brief** – Append a short paragraph (2‑3 sentences) that summarizes the benefit of the comparison page for SEO and conversion. End with a call‑to‑action for the sales team. Save the file as “comparison‑brief.md”.
   *Success sign:* the file is under 1 KB, all headings are correctly nested, and the schema validates.

## Common pitfalls and how to spot them

**Missing citations**. If a claim lacks a link, the page may be flagged for unverifiable content. Scan the document for any parentheses without a URL.

**Mismatched heading levels**. An H3 without a preceding H2 breaks the hierarchy and confuses screen readers. Use your editor’s outline view to confirm the order H2 → H3 → H3.

**Invalid JSON‑LD**. A stray comma or typo will stop search engines from reading the schema. Paste the block into the Rich Results Test after each edit; the tool will point out the exact line.

**Overly generic language**. Claims like “best performance” without data are useless for both users and citation engines. Replace with a concrete metric from your source.

If you encounter any of these symptoms, revert to the step where the issue first appears and correct it before moving on.

[See how we do it](/services/seo-growth)

### Validate the content for SEO visibility

1. **Run a structured‑data test** – After you paste the JSON‑LD block into the page, open the [Rich Results Test](https://search.google.com/test/rich-results) (no link needed in the text). Paste the entire HTML source and click “Test.”
   *What to look for:* the tool should list a “ProductComparison” result with each attribute displayed. If it reports “Missing required field” or “Invalid type,” note the line number, correct the JSON, and re‑run.

2. **Check the on‑page rendering** – View the live page in a browser and use the developer tools (Ctrl + Shift + I). In the Elements tab, search for `application/ld+json`. Confirm that the block appears exactly once and that all quotation marks are straight (no smart quotes).

3. **Confirm crawlability** – In Google Search Console, submit the page URL for “Inspect URL.” The report will tell you if Google can fetch the page and whether any structured‑data warnings exist. A green “Coverage” status means the page is ready for indexing.

4. **Verify the claims are indexed** – After a few hours, perform a site: search (`site:yourdomain.com "Feature A vs Feature B"`). If the comparison snippet appears in the SERP preview, the schema is recognized. If not, double‑check that each claim’s citation URL is reachable and that the source contains the exact wording you used.

### Keep the brief under version control

**Create a lightweight repo**. Even a single‑file markdown can live in a private Git repository. Commit the initial draft with the message “Initial brief – core attributes.”

**Tag each iteration**. After you add the heading hierarchy, tag the commit as `v1-headings`. When the JSON‑LD is added, tag as `v2-schema`. This makes it easy to roll back if a later edit introduces a validation error.

**Use a diff tool**. Before sending the file to the developer, run `git diff` to spot accidental whitespace changes or stray characters that could break the JSON. The diff will also show when citation URLs are added or removed, ensuring nothing is lost.

### Extending the brief for multiple comparisons

If your SaaS needs more than one versus page (e.g., “Feature A vs Feature C” or “Plan 1 vs Plan 2”), follow these additional steps:

1. **Duplicate the template** – Copy the original `comparison‑brief.md` to a new file named `comparison‑brief‑feature‑c.md`. The only differences will be the product names and attribute values.

2. **Maintain a master attribute list** – Keep a spreadsheet that lists every attribute you might compare across products. When you create a new brief, filter the list to the top five relevant attributes and copy them into the markdown. This prevents accidental omission of key differentiators.

3. **Use a single JSON‑LD block per page** – Each page should have its own `ProductComparison` object. Do not merge multiple comparisons into one block; search engines treat each block independently and may discard the entire markup if they detect mixed product IDs.

4. **Automate citation checks** – Write a short script (Python or Bash) that extracts every URL in parentheses and runs `curl -I` to confirm a 200 OK response. Integrate the script into your CI pipeline so any broken link flags the commit before it reaches the developer.

### Handing off to the developer

**Provide a one‑page handoff checklist**. Append a short “Developer Checklist” to the bottom of the markdown file:

☐ Confirm the file encoding is UTF‑8.

☐ Verify that the JSON‑LD block is placed inside a `` tag.

☐ Ensure the comparison table in HTML uses `` for attribute names and `` for values, matching the order in the JSON‑LD.

☐ Run the Rich Results Test and paste the resulting URL into the ticket.

**Specify the target template**. Mention the exact front‑end component the page should use (e.g., `ComparisonTable.jsx` in the React codebase). Include the component’s import path so the developer can drop the markdown into the CMS without searching for the right module.

**Set a small sprint goal**. Since the brief is designed for a one‑day turnaround, define the sprint as “Implement one comparison page from markdown to live HTML.” This keeps scope tight and avoids scope creep that can delay delivery.

**Include a sanity‑check script**. Add a short Node.js script that reads the generated HTML file and logs “Schema valid” if the Rich Results Test API returns a success code. The developer can run `node check-schema.js` after deployment to confirm everything works in production.

### Monitoring the page after launch

**Track structured‑data impressions**. In Google Search Console, navigate to “Enhancements → ProductComparison.” The dashboard shows how many times Google displayed the comparison rich result. A sudden drop may indicate a schema error introduced during a later site update.

**Watch for citation decay**. External sources can move or be removed. Schedule a quarterly review of all citation URLs. Use the same script from the “Automate citation checks” step to flag any dead links; replace them with fresh, authoritative sources.

**Measure user interaction**. Add an event listener to the comparison table that fires on clicks of each attribute row. Capture the data in your analytics platform to see which claims drive the most engagement. This informs future briefs: attributes that never get clicked can be replaced with more compelling differentiators.

**Iterate on the brief**. If after a month you notice a particular attribute consistently under‑performing (low click‑through, no schema impressions), revisit the underlying claim. Update the wording, find a stronger source, or consider swapping the attribute for a more relevant one.

By following these deeper steps, you turn a one‑page brief into a repeatable, quality‑assured artifact that fits cleanly into a sprint, survives code changes, and keeps your comparison pages both user‑friendly and search‑engine‑ready.

Comppound uses a similar disciplined template to keep every developer sprint predictable and error‑free. [See how we do it](/services/seo-growth).

## Keep reading

- [How to Brief a Comparison Page for Dev in One Day](/blog/how-to-brief-a-comparison-page-for-dev-in-one-day)
- [Brief a Feature Comparison Page for Dev Sprint Delivery](/blog/brief-a-feature-comparison-page-for-dev-sprint-delivery)
- [Brief Developer Add Schema Sprint for AI‑Ready Feature Page](/blog/brief-developer-add-schema-sprint-for-aiready-feature-page)

## Frequently asked questions

### What schema type should I use for a comparison page?

Use the “ProductComparison” type in JSON‑LD, listing each product and mapping every attribute to the “featureComparison” property. This format is recognized by Google for rich results.

### How many attributes are optimal for a quick comparison?

Five to seven attributes keep the page scannable and fit comfortably in a single‑day sprint while still providing enough detail to differentiate the options.

### Do I need to include meta tags in the brief?

Include a short meta description derived from the final summary paragraph. Keep it under 160 characters and embed the primary keyword phrase.

## About Comppound

Comppound runs SEO and AI search for B2B SaaS companies: a person sets the plan and reviews samples and every high-risk page, and AI speeds up production.

- [See SEO Growth](https://comppound.com/services/seo-growth): Buyers compare before they book a demo. Are your pages there when they do?
- [See pricing](https://comppound.com/pricing): Want the content written, reviewed and published for you?