# WordPress Plugin Readme.txt Optimization Cheat Sheet

Use this cheat sheet to audit and optimize WordPress plugin readme.txt files for maximum discoverability and conversions.

---

## WordPress.org Ranking Algorithm Summary

The algorithm uses this formula to rank plugins in search results:

```
Score = text_relevance x 0.375 x log2(active_installs) x 0.25 x log2(support_threads_resolved) x 0.25 x sqrt(rating) x freshness_decay x compatibility_decay
```

### Key Algorithm Factors

**Text relevance is determined by matching search terms against 7 fields (in order of weight):**

1. Plugin title (HIGHEST WEIGHT - more than all others combined)
2. Excerpt/short description (SECOND HIGHEST)
3. Full description (including FAQ and changelog)
4. Tags (only first 5 are indexed)
5. Plugin slug
6. Author name
7. Contributor names

**Critical ranking factors:**
- All search terms must appear somewhere in the readme.txt or the plugin won't show up for that search
- Exact phrase matches outrank scattered keywords
- Plugins with 0 reviews default to 2.5 stars (ranking penalty)
- Updates within 180 days avoid freshness decay penalties
- "Tested up to" field must be current to avoid compatibility penalties

---

## Section 1: Plugin Title Optimization

**Algorithm Weight:** MAXIMUM (More than all other fields combined)

### DO:
- Put primary keyword at the BEGINNING
- Use exact phrases people actually search
- Keep under 50 characters (truncates in search results)
- Make it descriptive and benefit-focused
- Use format: [Primary Keyword] - [Benefit or Differentiator]

### DON'T:
- Start with "WordPress" (redundant, trademark violation)
- Use clever/brand names without keywords (e.g., "SmartForms")
- Use vague terms like "Ultimate," "Pro," "Best"
- Exceed 50 characters

### Good Title Examples:
- "Contact Form Builder - Drag & Drop Form Creator"
- "Image Optimizer - Compress & Resize Images"
- "WooCommerce Product Feed - Google Shopping Integration"
- "Backup & Restore - Complete WordPress Backup Plugin"

### Title Validation Criteria:
- Primary keyword appears at the beginning
- Keyword matches what users actually search
- Under 50 characters
- Descriptive of actual function
- Doesn't start with "WordPress"

### Audit Questions:
1. What is the primary keyword users search for in this plugin's category?
2. Does the current title include that keyword at the beginning?
3. Is the title under 50 characters?
4. What would be a more optimized title following the formula?

---

## Section 2: Short Description (Excerpt) Optimization

**Algorithm Weight:** SECOND HIGHEST (After title)

**Character Limit:** 150 characters maximum

### DO:
- Lead with primary keyword (reinforces title)
- Focus on benefits, not features
- Use active voice
- Answer "Why should I click?"
- Use format: [What it does] + [Key benefit] + [Differentiator]
- Be specific with numbers/results when possible

### DON'T:
- Waste space on vague claims ("powerful," "easy," "flexible")
- Use passive voice
- Lead with generic statements
- Include claims without specifics ("#1 rated" without context)
- Exceed 150 characters

### Good Excerpt Examples:
- "Create beautiful contact forms with drag-and-drop builder. No coding required. Spam protection included." (116 chars)
- "Optimize images automatically on upload. Reduce file size by 70% without quality loss. Works with any theme." (111 chars)
- "Backup your entire site in one click. Schedule automatic backups. Restore with a single click." (96 chars)

### Excerpt Validation Criteria:
- Starts with primary keyword
- Under 150 characters
- Uses active voice
- Includes specific benefits
- No generic filler words
- Differentiates from competitors

### Audit Questions:
1. Does the excerpt lead with the primary keyword?
2. Is it under 150 characters?
3. Are benefits specific and measurable?
4. Could a competitor use the exact same words?
5. What would be a more conversion-focused excerpt?

---

## Section 3: Full Description Optimization

**Algorithm Weight:** MEDIUM (Indexed for text matching)

**Target Word Count:** 2,500+ words

**Purpose:** Capture long-tail search queries

### DO:
- Write 2,500+ words of comprehensive documentation
- Use natural keyword variations throughout
- Include extensive FAQ section
- Add "How to" sections for common use cases
- Document troubleshooting steps
- Explain integrations with related products
- Use headers (##) liberally for structure
- Answer every question users might search

### DON'T:
- Keyword stuff
- Use only brief feature lists
- Skip FAQ section
- Write in overly technical jargon
- Forget to use headers for organization

### Section Structure Template:

```
## Description
[Comprehensive overview with natural keyword variations]

## Key Features
[Detailed explanations, not just bullet points]

## Easy Drag-and-Drop Form Builder
[Explain this feature with searchable terms]

## Spam Protection Features
[Detail how it works]

## How to [Common Use Case 1]
[Step-by-step guide]

## How to [Common Use Case 2]
[Step-by-step guide]

## Integration with [Related Product]
[Explain integration]

## Frequently Asked Questions

### How do I [common search query]?
[Comprehensive answer]

### Why isn't [common problem]?
[Troubleshooting]

## Troubleshooting
[Common issues and solutions]
```

### Description Validation Criteria:
- 2,500+ words total
- Primary keyword appears 5-10 times naturally
- Related keywords/variations included
- FAQ section with 10+ questions
- "How to" sections for common use cases
- Troubleshooting section
- Integration guides where applicable
- Uses ## headers for structure
- Answers searchable questions

### Audit Questions:
1. What is the current word count? (Target: 2,500+)
2. How many times does the primary keyword appear naturally?
3. What related search terms are missing?
4. What FAQ questions should be added based on the plugin's category?
5. What "how to" sections would capture long-tail searches?
6. What common troubleshooting queries should be documented?

---

## Section 4: Tags Optimization

**Algorithm Weight:** LOW (But still indexed)

**Critical Rule:** ONLY THE FIRST 5 TAGS ARE INDEXED

### DO:
- Use actual search terms users type
- Include product integrations (e.g., "woocommerce")
- Mix broad and specific tags
- Research what top competitors use
- Validate each tag by browsing it on WordPress.org
- Use EXACTLY 5 tags (no more, no less)

### DON'T:
- Use more than 5 tags (ignored + potentially flagged as spam)
- Use competitor names as tags (trademark violation)
- Use vague category terms nobody searches
- Use tags for keywords already in title

### Tag Selection Framework:

For each potential tag, ask:
1. Is this a term users actually search?
2. Does browsing this tag on WordPress.org show similar plugins?
3. Is this a product integration users search for?
4. Do top competitors in my category use this?

### Good Tag Examples by Category:

**Contact Form Plugin:**
- contact-form
- form-builder
- email
- lead-generation
- gdpr

**Image Optimizer:**
- image-optimization
- compression
- performance
- seo
- lazy-load

**Backup Plugin:**
- backup
- restore
- migration
- security
- database

### Tag Validation Criteria:
- Exactly 5 tags (no more, no less)
- Each tag represents actual search term
- Browsing each tag shows relevant similar plugins
- Mix of broad and specific terms
- Includes relevant product integrations
- No competitor names
- No trademark violations

### Audit Questions:
1. How many tags are currently listed? (Should be exactly 5)
2. Which tags represent actual search terms vs. vague categories?
3. What tags do the top 5 competitors in this category use?
4. What product integrations should be included as tags?
5. What would be the optimal 5 tags for this plugin?

---

## Section 5: Changelog Optimization

**Algorithm Weight:** LOW (But indexed for text matching)

**Purpose:** Signal active development + keyword reinforcement

### DO:
- Describe features with searchable terms
- Update regularly (every 90 days minimum)
- Use descriptive language, not just version numbers
- Include relevant keywords naturally

### DON'T:
- Write minimal entries ("Bug fixes")
- Let it go stale (180+ days triggers decay)
- Just list version numbers without context

### Good Changelog Examples:

**Bad:**
```
= 2.1 =
* Bug fixes
* Performance improvements
```

**Good:**
```
= 2.1 =
* Added spam protection with Google reCAPTCHA integration
* Improved email delivery with SMTP configuration options
* Fixed contact form submission issues on mobile devices
* Enhanced drag-and-drop form builder interface
* Added conditional logic for multi-step forms
```

### Changelog Validation Criteria:
- Latest update within past 90 days
- Each entry describes features with keywords
- No generic "bug fixes" without specifics
- Entries use searchable terminology

### Audit Questions:
1. When was the last update? (Should be within 90 days)
2. Do changelog entries use descriptive, searchable language?
3. How can changelog entries be rewritten to include more keywords?

---

## Section 6: Technical Metadata

### Fields to Verify:

**Tested up to:**
- Set to latest WordPress version (or within 1 major version)
- Updates trigger compatibility_decay penalty if outdated

**Requires at least:**
- Set to reasonable minimum (don't exclude users unnecessarily)

**Requires PHP:**
- Set to reasonable minimum PHP version

**Stable tag:**
- Matches latest version in changelog

**License:**
- Clearly specified (GPL v2+ is standard)

### Audit Questions:
1. Is "Tested up to" set to the latest WordPress version?
2. Are version requirements reasonable and current?

---

## Section 7: Screenshots and Assets

**Not Indexed by Algorithm BUT Critical for Conversions**

### DO:
- Show the plugin actually working (not just UI)
- Demonstrate key features visually
- Use descriptive captions with keywords
- Include 5-8 screenshots
- Show before/after if applicable
- Make screenshots clear at 1200px+ width

### DON'T:
- Skip screenshots entirely
- Use low-resolution images
- Show only admin screens without context
- Write vague captions

### Screenshot Caption Template:

**Instead of:** "Settings page"
**Use:** "Drag-and-drop form builder interface with spam protection options"

**Instead of:** "Frontend display"
**Use:** "Beautiful contact forms displayed on your site with custom styling"

### Assets Validation Criteria:
- 5-8 high-quality screenshots included
- Screenshots show plugin functionality, not just UI
- Each caption includes relevant keywords
- Banner image is professional and clear
- Icon is recognizable at small sizes

---

## Complete Readme Audit Checklist

### Title & Excerpt:
- Title under 50 chars with primary keyword first
- Excerpt under 150 chars with benefit-focused copy
- Both use exact search terms users type

### Description:
- 2,500+ words total
- Comprehensive FAQ (10+ questions)
- "How to" sections for common use cases
- Troubleshooting section
- Integration guides where applicable
- Uses ## headers for structure

### Tags:
- Exactly 5 tags
- All represent actual search terms
- Include relevant integrations
- No competitor names

### Technical:
- "Tested up to" is current (within 1 major version)
- Changelog updated within 90 days
- Version numbers consistent

### Assets:
- 5-8 quality screenshots with keyword-rich captions
- Professional banner and icon

---

## Common Optimization Patterns

### Pattern 1: Keyword-Deficient Title
- **Problem:** Generic or branded title without search keywords
- **Example:** "SmartForms Pro"
- **Fix:** "Contact Form Builder - Drag & Drop Form Creator"
- **Impact:** Makes plugin discoverable for "contact form builder" searches

### Pattern 2: Vague Excerpt
- **Problem:** Generic benefits without specifics
- **Example:** "A powerful and easy-to-use form plugin for WordPress."
- **Fix:** "Create beautiful contact forms with drag-and-drop builder. No coding required. Spam protection included."
- **Impact:** Converts browsers into clickers with specific benefits

### Pattern 3: Minimal Description
- **Problem:** 200-word description with basic feature list
- **Fix:** 2,500+ word comprehensive guide with FAQ, how-tos, troubleshooting
- **Impact:** Captures long-tail searches like "how to add contact form to sidebar"

### Pattern 4: Too Many Tags
- **Problem:** 15 tags listed (only first 5 indexed)
- **Fix:** Carefully selected 5 tags based on search volume and competitor research
- **Impact:** Focuses tag value on most important terms

### Pattern 5: Stale Changelog
- **Problem:** Last update 8 months ago
- **Fix:** Update to latest WordPress version, commit minor changes every 90 days
- **Impact:** Avoids freshness_decay ranking penalty

---

## Success Metrics

### Immediate (1-7 days):
- Search impressions for primary keywords
- Click-through rate from search results
- Position in search for primary keywords

### Short-term (30-60 days):
- Daily active installs
- Total active installs
- Search ranking position changes

### Long-term (90+ days):
- Review acquisition rate
- Average rating improvement
- Support thread volume and resolution

---

## Red Flags to Avoid

**These will hurt your rankings or get you banned:**

- Keyword stuff (using keywords unnaturally/excessively)
- Use competitor names in slug, title, or tags
- List more than 5 tags
- Let plugin go 180+ days without updates
- Use generic placeholder content
- Copy competitors' descriptions verbatim
- Make false claims about features
- Use bait-and-switch tactics in descriptions

---

## Final Note

This cheat sheet is based on:
- WordPress.org's disclosed ranking algorithm (2017 Elasticsearch implementation)
- Analysis of top-ranking plugins across categories
- WordPress.org official documentation and guidelines
- Real-world optimization case studies

**The algorithm prioritizes plugins that:**
1. Match search queries accurately (text relevance)
2. Are actively maintained (freshness)
3. Have strong user satisfaction (ratings)
4. Provide good support (resolution rate)
5. Have proven usage (active installs)

Your readme.txt controls text relevance directly and influences freshness through the changelog. Optimizing it well sets the foundation for everything else.