# How to Brief a Comparison Page for Dev in One Day

> Get a ready‑to‑ship brief that lets a developer build a comparison page in a day, with exact sections, data sources, and layout guidelines, and clear QA steps.

Source: https://comppound.com/blog/how-to-brief-a-comparison-page-for-dev-in-one-day (published 2026-10-17)

A brief that a developer can turn into a live comparison page in a single workday includes the data to compare, the layout plan, and the copy cues needed for SEO and AI citation. You can create that brief in five logical steps without writing the full page yourself.

## What the final brief looks like
The deliverable is a single document (Google Doc, Confluence page, or markdown file) that a developer can open and start coding. It contains:

| Element | Description | Example |
|---|---|---|
| Page goal | The SEO question the page answers (e.g., “Which SaaS analytics tool offers the best integration?”) | “Help B2B SaaS founders choose a data‑visualization platform.” |
| Target keywords | Primary and secondary keywords for on‑page SEO | Primary: *SaaS analytics comparison*; Secondary: *best data visualization tool*. |
| Competitor list | The exact products or services to compare, with URLs | Acme Analytics, DataWave, Insightify. |
| Comparison criteria | Columns that will appear on the page, written as short headings | Pricing, Integration, Export Formats, Support SLA. |
| Data source notes | Where each cell’s value comes from (pricing page, API, or interview) | “Pricing taken from 2024 pricing table on Acme site.” |
| Copy hooks | One‑sentence pointers for the dev to add as H2 or tooltip text | “Acme’s seamless API saves 2 hours of engineering time per month.” |
| QA checklist | Items the writer or SEO lead must verify before launch | All numbers verified, alt text added, schema present. |

Having all of these in one place removes guesswork and lets the developer focus on markup, not research.

## Collect the comparison data
1. List the competitor URLs you need to compare.
2. Pull the required numbers (price, feature limits, release dates) from each site or from a recent internal audit.
3. Store the raw data in a spreadsheet with columns matching the criteria you plan to show.

**How to know it worked:** The spreadsheet should have a row for every competitor and a column for every criterion you intend to display. If any cell is blank, you have a data gap that must be filled before moving on.

## Choose the comparison structure
Decide whether the page will use a table, a card grid, or an accordion layout. For most SEO‑focused pages a simple HTML table with `thead` and `tbody` is fastest for a dev to implement and easy for search engines to parse.

**How to know it worked:** Sketch a quick wireframe on paper or in a tool like Figma. If the wireframe shows column headings matching your spreadsheet columns and rows matching competitor entries, the structure aligns.

## Draft the brief template
Create a markdown template that mirrors the final HTML structure. Include placeholders for each data point and copy hook. For example:

```markdown
## {Page Goal}

| {Criterion 1} | {Criterion 2} | {Criterion 3} |
|---|---|---|
| {{Acme Analytics}} | {{DataWave}} | {{Insightify}} |
| {{Acme Pricing}} | {{DataWave Pricing}} | {{Insightify Pricing}} |
| {{Acme Hook}} | {{DataWave Hook}} | {{Insightify Hook}} |
```

Add a short note beneath the table explaining any required schema markup (e.g., `Product` schema).

**How to know it worked:** Open the markdown in your preview tool; all placeholders should resolve to real values when you paste data from the spreadsheet. No placeholder text should remain.

## Review for dev readiness
Before handing the brief to a developer, run a checklist:

- All URLs are absolute and reachable.
- Every numeric value has a citation note (e.g., “source: pricing page, 12 Oct 2023”).
- The copy hooks do not exceed 140 characters (fits meta description limits).
- The markdown syntax validates without errors.

**How to know it worked:** A teammate who hasn’t seen the brief should be able to read the checklist and confirm every item without needing additional clarification.

## Hand off and confirm delivery
Send the brief file to the assigned developer with a short message: “Please build the comparison page using the markdown template attached; aim to publish by EOD.” Include the QA checklist so the dev can tick items as they finish each part.

**How to know it worked:** The developer replies with a link to a staging URL. Open the page, verify that the table displays all criteria, and run a quick SEO audit (e.g., using Chrome’s Lighthouse) to confirm headings and schema are present.

## Common pitfalls and how to detect them
| Symptom | Typical cause | Fix |
|---|---|---|
| Missing numbers in the live page | Data not copied from spreadsheet into markdown | Re‑open the brief, copy the missing row, push the update. |
| Layout looks like a list, not a table | Developer used `
` instead of `` | Point to the “Choose the comparison structure” section; ask for correct HTML element. |
| SEO keywords not appearing in H1 or meta | Copy hooks placed in tooltip only | Move primary keyword into the page title line of the brief. |
| AI citations return “no source” | Source notes omitted or URLs broken | Verify each “source:” note matches a live URL; fix broken links. |

When a problem matches a symptom, trace it back to the originating step in the brief and correct the source document before the next iteration.

[Explore SEO Growth](/services/seo-growth)

### – Collect the comparison data (expanded)

**Define a data‑gathering checklist** – before you open a spreadsheet, write a short list of the exact fields you need for each competitor. For a SaaS analytics comparison those fields often include:

* Plan name and price (annual vs monthly)
* Core feature limits (e.g., max dashboards, data rows)
* Integration count (APIs, native connectors)
* Support level (SLA response time, live chat availability)

Write the checklist in a separate document or as the first rows of the spreadsheet. When you fill a row, tick the box next to each field. If any box stays unchecked, you have a missing piece that must be sourced before moving on.

**Use a single source of truth** – store the spreadsheet in a shared drive (Google Sheets, OneDrive) with read/write permissions limited to the SEO lead and the analyst doing the research. This prevents the “I thought I’d already added the price” problem that often shows up later in the hand‑off.

**Example** – Say you run a company called *Graphify* that wants to compare three analytics tools. Your checklist might look like:

| Field | Acme Analytics | DataWave | Insightify |
|---|---|---|---|
| Monthly price | your price tier 1 | your price tier 2 | your price tier 3 |
| Annual price (discount applied) | your annual tier 1 | your annual tier 2 | your annual tier 3 |
| Max dashboards | 10 | 8 | 12 |
| API endpoints | 25 | 18 | 30 |
| Support SLA | 24‑hour response | Business hours | 4‑hour response |

When the spreadsheet contains a complete row for each competitor, you can be confident the data layer of the brief is ready.

### – Choose the comparison structure (expanded)

**Why the layout matters for AI citation** – Search engines that generate direct answers pull structured content from tables, definition lists, and schema‑rich markup. A plain list of bullet points is harder for a model to extract a concise answer from. By committing to a table‑based layout you give the AI a clear matrix to reference.

**Wireframe sanity check** – After you sketch the wireframe, run a quick “copy‑fit” test: copy the longest headline you plan to use into the wireframe cell and see if it overflows. If it does, you either need to shorten the headline or increase column width. This prevents later CSS tweaks that could break the layout on mobile.

**Alternative layouts for specific goals** – If the page is intended to rank for “best pricing” queries, a pure table works best. If the focus is on side‑by‑side feature comparison where each feature needs more description, a card‑grid may be preferable. Decide this before you lock the wireframe, and document the decision in the brief so the developer knows which HTML components to use.

### – Draft the brief template (expanded)

**Placeholder naming convention** – Use a consistent token pattern so the developer can script a find‑and‑replace. For example, wrap every dynamic value in double curly braces and prefix it with the competitor name: `{{Acme_Pricing}}`, `{{DataWave_Integration}}`. Consistency makes it possible to generate the final page with a simple script rather than manual copy‑paste.

**Add schema notes directly in the template** – Insert comments that remind the developer to add `Product` or `SoftwareApplication` schema for each competitor row. Example comment:

```markdown

```

These comments are ignored by the markdown renderer but stay visible in the source file, ensuring the SEO layer isn’t forgotten.

**Include a “fallback copy” row** – Occasionally a data point will be unavailable (e.g., a competitor does not publish its pricing). Add a row titled “Pricing (if disclosed)” with a placeholder like `{{Acme_Pricing_Unavailable}}`. In the brief you can note: “If unavailable, write ‘Contact sales for pricing’.”

### – Review for dev readiness (expanded)

**Automated linting** – Before the hand‑off, run the markdown file through a linting tool (such as markdownlint). Configure a rule that flags any remaining `{{...}}` tokens. If the linter reports zero errors, you have eliminated stray placeholders.

**Link validation script** – Use a small script (or a Chrome extension) that checks every URL in the brief for a 200 HTTP status. Broken links are a common cause of AI citations returning “no source”. Document the script command in the brief so another team member can rerun it after any update.

**Accessibility quick check** – Verify that any copy hooks intended for tooltips also have a plain‑text counterpart. For instance, if a hook reads “Acme’s seamless API saves 2 hours of engineering time per month,” also add a hidden `` with the same text for screen readers. Note this requirement in the checklist.

### – Hand off and confirm delivery (expanded)

**Version control** – Save the brief in a version‑controlled repository (Git, Bitbucket) and tag the commit with a short identifier like `compare‑page‑v1`. This gives both the SEO lead and the developer a rollback point if the dev later discovers a data error.

**Staging verification list** – When the developer shares the staging URL, run through a concise list:

Our system at Comppound records each brief in a shared doc, so the handoff is reproducible and audit‑ready. [See how we do it](/services/seo-growth).

## Frequently asked questions

### What length should the comparison table be for SEO?

The table should include enough rows to cover all relevant competitors but stay under a dozen to avoid overwhelming the page. If you have more than ten competitors, consider splitting into multiple pages or using a filter widget.

### Do I need to add schema markup manually?

Yes. Include a brief note in the brief template specifying the required `Product` or `ItemList` schema. The developer can then paste the JSON‑LD snippet into the page head.

### Can I reuse the same brief for multiple comparison pages?

Reuse is possible if the criteria and competitors overlap, but update the page goal, target keywords, and any product‑specific hooks for each new page to keep the content unique.