ReadMe.com Linter Instructions for AnyTrack Documentation

These instructions are designed for ReadMe.com's Linter feature to enforce documentation quality standards across AnyTrack's conversion tracking and attribution guides.

Error Rules

Front Matter Metadata Description Must Have Value

The metadata.description field in front matter must contain an actual description value, not an empty string.

Why this matters: An empty metadata.description causes ReadMe to incorrectly generate page slugs and breaks OpenGraph metadata for social sharing.

Bad:

metadata:
  title: Cross-Domain Tracking: Blog to Shopify Store Setup Guide
  description: ''
  robots: index

Good:

metadata:
  title: Cross-Domain Tracking: Blog to Shopify Store Setup Guide
  description: Track conversions across blog and Shopify domains with AnyTrack. Complete setup guide for maintaining attribution from review sites to store purchases.
  robots: index

What to check:

metadata.description must not be an empty string ('')
Description should be 120-160 characters
Description should summarize the guide's value proposition
Use active language with relevant keywords

Front Matter Metadata Title Must Be Single Line

The metadata.title field must be a single-line value, not split across multiple lines with empty strings.

Why this matters: Multi-line or malformed title values break YAML parsing and cause ReadMe to generate incorrect page titles and slugs.

Bad:

metadata:
  title: ''
  Cross-Domain Tracking: Blog to Shopify Store Setup Guide
  description: Track conversions across domains

Good:

metadata:
  title: Cross-Domain Tracking: Blog to Shopify Store Setup Guide
  description: Track conversions across domains

What to check:

metadata.title must be on a single line with its value
No empty strings ('') on separate lines
Title should be 55-60 characters for optimal SEO
Use colons or dashes to separate concepts if needed

AnyTrack Product Name Capitalization

Capitalize "AnyTrack" correctly as one word with capital A and T.

Bad: anytrack, Anytrack, Any Track, any track

Good: AnyTrack

Tracking Implementation Terms

Use "Tracking Tag" instead of deprecated "Tracking Pixel" terminology.

Bad: Install the tracking pixel on your website

Good: Install the Tracking Tag on your website

Ad Platform Names Must Be Capitalized Correctly

Ad platform names must use proper capitalization and official product names.

Bad: Facebook ads, facebook Ads, Tiktok ads, google ads, meta ads

Good: Facebook Ads, TikTok Ads, Google Ads, Meta Ads

Analytics Platform Full Names

Use full, properly capitalized product names for analytics platforms.

Bad: GA, GA4, google analytics, google tag manager, GTM

Good: Google Analytics, Google Analytics 4, Google Tag Manager

Server-Side Tracking Term

Use "Conversion API" for server-side tracking implementations.

Bad: Server API, CAPI, conversion api, Conversion api

Good: Conversion API

Technical Terms Must Use Backticks

Wrap technical terms, code elements, parameters, and API names in backticks.

Bad: Add the event_name parameter to track the FormSubmit event

Good: Add the event_name parameter to track the FormSubmit event

Examples of what needs backticks:

Parameters: event_name, click_id, fbp, gclid
Events: FormSubmit, Purchase, Lead
Code: AnyTrack('trigger', 'Purchase')
File names: index.html, config.json
Command-line tools: npm install, git push

Placeholder Content Must Be Removed

Flag any placeholder text indicating incomplete content.

Examples to flag: TODO, FIXME, TK, [insert details], Lorem ipsum, Coming soon, [screenshot needed], [add example]

Why this matters: Placeholder text indicates the content is not ready for publication.

Missing Context for Technical Steps

Technical instructions that reference UI locations must include the full navigation path.

Bad: Copy the API key from your dashboard

Good: Copy the API key from your AnyTrack dashboard under Settings > API Keys

Style Guide Rules

What, Why, How Structure

Organize procedural guides and feature explanations using the What, Why, How structure.

Structure:

What: Define what the feature/concept is
Why: Explain why it matters and when to use it
How: Provide step-by-step implementation instructions

When to apply:

Feature guides
Integration tutorials
Setup instructions
Technical how-tos

When NOT to apply:

FAQ pages
Contact information
Release notes
Simple reference lists

Clear and Concise Writing

Write clear, direct content that gets to the point quickly.

Guidelines:

Keep paragraphs to 3-4 sentences maximum
Avoid unnecessary filler words
Each sentence should serve a clear purpose
Don't repeat information in different ways
Help users find information quickly

Bad: In order to be able to start tracking your conversions with AnyTrack, you will need to install the tracking code on your website, which will allow the system to begin collecting the data.

Good: Install the AnyTrack Tracking Tag on your website to start tracking conversions.

Scannable Content

Structure content for easy scanning with clear visual hierarchy.

Best practices:

Use descriptive H2/H3 headings
Break long content into sections
Use bullet points for lists
Keep paragraphs short
Add visual breaks between sections
Use callout boxes for important notes

Action-Oriented Language

Use active voice and direct instructions that tell readers exactly what to do.

Bad: The tracking code should be placed in the header section of your website

Good: Place the Tracking Tag in your website's <head> section

Bad: The conversion can be tracked by clicking the button

Good: Click the button to track the conversion

Professional but Approachable Tone

Balance professionalism with warmth and accessibility.

Guidelines:

Write conversationally but professionally
Avoid overly formal or academic language
Don't use slang or be too casual
Show you're helping users succeed
Be confident and authoritative without being condescending

Warning Rules

Technical Terms Need Plain Language Explanation

When introducing technical concepts, provide the technical term first, then immediately explain it in accessible language.

Bad: Use the Conversion API to track events

Good: Use the Conversion API—a server-side tracking method—to send conversion data directly from your server to ad platforms

Pattern: Technical Term—plain language explanation—usage context

Avoid Jargon Without Context

Don't assume readers understand technical terminology without explanation.

Bad: Configure your postback URL to send server-to-server events

Good: Configure your postback URL—a webhook that sends conversion data from your server to ad platforms—to enable server-to-server event tracking

Hedging Language Weakens Instructions

Avoid uncertain or overly cautious language that undermines user confidence.

Bad:

You might want to consider installing the Tracking Tag
It may be helpful to configure cross-domain tracking
You could potentially use this feature

Good:

Install the Tracking Tag to start tracking conversions
Configure cross-domain tracking to maintain attribution
Use this feature to track conversions across domains

Passive Voice Reduces Clarity

Use active voice for clearer, more direct instructions.

Bad: The conversion will be tracked when the button is clicked by the user

Good: AnyTrack tracks the conversion when users click the button

Bad: The data is sent to Google Ads by the Conversion API

Good: The Conversion API sends data to Google Ads

Weak Constructions Dilute Message

Avoid weak phrases that add no value.

Phrases to avoid:

"You can" (just state the action)
"There is/are" (restructure the sentence)
"In order to" (use "to")
"It is possible to" (just state it directly)

Bad: You can configure the tracking settings in the dashboard

Good: Configure the tracking settings in your dashboard

Bad: In order to track conversions, install the Tracking Tag

Good: To track conversions, install the Tracking Tag

Front Matter Best Practices

Complete Front Matter Template

Every guide should have properly formatted front matter:

---
title: [Main Page Title]
excerpt: >-
  [Brief description of the guide's content, 1-2 sentences]
deprecated: false
hidden: false
metadata:
  title: [SEO-optimized title, 55-60 chars]
  description: [Meta description for search/social, 120-160 chars]
  robots: index
  keywords:
    - [primary keyword phrase]
    - [secondary keyword phrase]
    - [tertiary keyword phrase]
next:
  description: ''
---

Front Matter Field Guidelines

title: The H1 that appears at the top of the page

Clear, descriptive
No need for keyword stuffing
User-focused

excerpt: Brief description shown in search results within ReadMe

1-2 sentences
Summarizes what the guide covers
Can use multi-line YAML format with >-

metadata.title: The <title> tag and OpenGraph title

55-60 characters optimal
Include primary keyword
Format: "[Primary Keyword]: [Specific Detail]" or "[Action] [Tool/Platform] [Outcome]"

metadata.description: The meta description and OpenGraph description

120-160 characters
Summarize value proposition
Include relevant keywords naturally
Action-oriented language
MUST NOT be empty ('')

metadata.keywords: Array of keyword phrases

3-5 keyword phrases
Most important first
Use actual phrases users search for
Include variations (e.g., "cross-domain tracking shopify" and "shopify cross-domain attribution")

Implementation Notes

Category Priorities

Errors = Must fix before publishing
Warnings = Review and fix unless there's a good reason not to
Style Guide = Qualitative assessment of overall documentation quality

False Positive Prevention

Some rules should not apply to:

Code blocks (already formatted)
Quoted text from external sources
Product names that don't follow standard capitalization
URLs and technical identifiers

Testing Approach

Before enabling a new rule:

Test on 5-10 existing articles
Check for false positives
Verify the rule catches the intended issues
Adjust thresholds if needed
Document any exceptions