Add documentation index for easy navigation
This commit is contained in:
parent
b2ec7fc805
commit
926d3aad25
|
|
@ -0,0 +1,258 @@
|
|||
# Documentation Index
|
||||
|
||||
Complete reference guide for all project documentation.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Quick Start
|
||||
|
||||
**New to this project?** Read in this order:
|
||||
1. `README.md` - Project overview and basic commands
|
||||
2. `WORKFLOW.md` - How to create new claims pages
|
||||
3. `CLAIMS_PAGE_GUIDELINES.md` - Strict image selection rules
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Files
|
||||
|
||||
### Core Workflow
|
||||
| File | Purpose | Last Updated |
|
||||
|------|---------|--------------|
|
||||
| **WORKFLOW.md** | Complete step-by-step process for creating claims pages | 2025-11-04 |
|
||||
| **CLAIMS_PAGE_GUIDELINES.md** | Strict image selection criteria (white bg, black text, red accents) | 2025-11-04 |
|
||||
|
||||
### Project Setup
|
||||
| File | Purpose | Status |
|
||||
|------|---------|--------|
|
||||
| **README.md** | Project overview, stats, and quick commands | ✅ Current |
|
||||
| **MIGRATION_SUMMARY.md** | Technical details of React SPA → Next.js SSG migration | ✅ Current |
|
||||
|
||||
### Deployment & DNS
|
||||
| File | Purpose | Status |
|
||||
|------|---------|--------|
|
||||
| **DOMAIN_SETUP_GUIDE.md** | Custom domain setup (kbanc.com → Netlify) | ✅ Current |
|
||||
| **NAMECHEAP_DNS_SETUP.md** | Complete DNS config preserving Google Workspace email | ✅ Current |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Documentation by Task
|
||||
|
||||
### "I want to create a new claims page"
|
||||
1. Read: `WORKFLOW.md` (complete process)
|
||||
2. Reference: `CLAIMS_PAGE_GUIDELINES.md` (image criteria)
|
||||
3. Use: Quality checklist in WORKFLOW.md
|
||||
|
||||
### "I need to understand the project structure"
|
||||
1. Read: `MIGRATION_SUMMARY.md` (technical architecture)
|
||||
2. Read: `README.md` (quick overview)
|
||||
|
||||
### "I'm setting up the custom domain"
|
||||
1. Read: `DOMAIN_SETUP_GUIDE.md` (Netlify setup)
|
||||
2. Read: `NAMECHEAP_DNS_SETUP.md` (DNS records)
|
||||
3. Follow: Step-by-step checklists in both files
|
||||
|
||||
### "I need to understand GEO optimization"
|
||||
1. Read: `MIGRATION_SUMMARY.md` → "Why This is Better for GEO"
|
||||
2. Read: `WORKFLOW.md` → "Extract Atomic Claims"
|
||||
3. Reference: Example claims throughout documentation
|
||||
|
||||
---
|
||||
|
||||
## 📊 Current Project Stats
|
||||
|
||||
**Last verified:** 2025-11-04
|
||||
|
||||
- **Total pages:** 15 static HTML files
|
||||
- **Claims pages:** 10 individual articles
|
||||
- **Build time:** ~3 seconds
|
||||
- **Deployment:** Auto-deploy via GitHub → Netlify
|
||||
- **Image policy:** White background + black text + red accents ONLY
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Key Concepts
|
||||
|
||||
### GEO (Generative Engine Optimization)
|
||||
Optimizing content for AI systems (ChatGPT, Claude, Perplexity) to extract and cite.
|
||||
|
||||
**Implementation:**
|
||||
- Static HTML with pre-rendered content
|
||||
- JSON-LD structured data embedded
|
||||
- Atomic claims (12-18 tokens each)
|
||||
- Clear, verifiable statements
|
||||
|
||||
### Atomic Claims
|
||||
Single, standalone statements optimized for LLM extraction.
|
||||
|
||||
**Requirements:**
|
||||
- 12-18 tokens (~15 words)
|
||||
- Independently verifiable
|
||||
- Includes specific data/metrics
|
||||
- Formatted for citation
|
||||
|
||||
### Image Compliance
|
||||
Strict visual criteria for infographics.
|
||||
|
||||
**Requirements:**
|
||||
- White background
|
||||
- Black text (primarily)
|
||||
- Red accents only
|
||||
- No photographs
|
||||
- No screenshots
|
||||
- Text-heavy content
|
||||
|
||||
---
|
||||
|
||||
## 📝 File Naming Conventions
|
||||
|
||||
### Article Slugs
|
||||
- Format: `lowercase-with-hyphens`
|
||||
- Examples: `amazon-ai-playbook`, `chatgpt-features`
|
||||
|
||||
### Images
|
||||
- Format: `[slug]-[description].png`
|
||||
- Examples: `amazon-process-diagram.png`
|
||||
|
||||
### CSV Files
|
||||
- Format: `[slug]-claims.csv`
|
||||
- Examples: `chatgpt-features-claims.csv`
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Common Commands
|
||||
|
||||
### Development
|
||||
```bash
|
||||
npm install # Install dependencies
|
||||
npm run dev # Start dev server
|
||||
npm run build # Build for production
|
||||
```
|
||||
|
||||
### Deployment
|
||||
```bash
|
||||
git add . # Stage changes
|
||||
git commit -m "..." # Commit with message
|
||||
git push # Deploy (auto-triggers Netlify)
|
||||
```
|
||||
|
||||
### Verification
|
||||
```bash
|
||||
npm run build # Must succeed before committing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Quality Standards
|
||||
|
||||
### Every Claims Page Must Have:
|
||||
- [ ] Exactly 5 atomic claims
|
||||
- [ ] Complete metadata (title, description, OG, Twitter)
|
||||
- [ ] Embedded JSON-LD schema
|
||||
- [ ] CSV file for download
|
||||
- [ ] Link to original article
|
||||
- [ ] Updated sitemap.xml
|
||||
- [ ] Entry in ClaimsLibrary component
|
||||
- [ ] Preview card on index page
|
||||
|
||||
### Every Image Must Have:
|
||||
- [ ] White background
|
||||
- [ ] Black text
|
||||
- [ ] Red accents only
|
||||
- [ ] Text-heavy content
|
||||
- [ ] No photographs
|
||||
- [ ] No screenshots
|
||||
|
||||
---
|
||||
|
||||
## 🔗 External Links
|
||||
|
||||
- **Live Site:** https://kbanc-nextjs.netlify.app
|
||||
- **GitHub Repo:** https://github.com/kbanc85/kbanc-nextjs
|
||||
- **Netlify Dashboard:** https://app.netlify.com/projects/kbanc-nextjs
|
||||
- **Source Material:** https://aiadopters.club
|
||||
|
||||
---
|
||||
|
||||
## 📞 Need Help?
|
||||
|
||||
### For Technical Issues:
|
||||
1. Check `WORKFLOW.md` → Troubleshooting section
|
||||
2. Review related documentation
|
||||
3. Check Netlify deployment logs
|
||||
|
||||
### For Content Questions:
|
||||
1. Review atomic claim examples in `WORKFLOW.md`
|
||||
2. Check existing claims pages for patterns
|
||||
3. Reference `CLAIMS_PAGE_GUIDELINES.md`
|
||||
|
||||
### For Deployment Issues:
|
||||
1. Verify build succeeds locally: `npm run build`
|
||||
2. Check GitHub Actions / Netlify logs
|
||||
3. Review `DOMAIN_SETUP_GUIDE.md`
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Documentation Maintenance
|
||||
|
||||
### When to Update This Documentation:
|
||||
|
||||
**WORKFLOW.md:**
|
||||
- Process changes
|
||||
- New file requirements
|
||||
- Quality standard updates
|
||||
|
||||
**CLAIMS_PAGE_GUIDELINES.md:**
|
||||
- Image criteria changes
|
||||
- New visual requirements
|
||||
|
||||
**README.md:**
|
||||
- Page count changes
|
||||
- New major features
|
||||
- Project stats updates
|
||||
|
||||
**MIGRATION_SUMMARY.md:**
|
||||
- Architecture changes
|
||||
- Build process updates
|
||||
- Page count updates
|
||||
|
||||
---
|
||||
|
||||
## 📈 Project Evolution
|
||||
|
||||
### Version History
|
||||
|
||||
**v1.0** (Nov 2, 2025)
|
||||
- Migrated from React SPA to Next.js SSG
|
||||
- 13 pages (homepage + 12 claim pages)
|
||||
- Basic GEO optimization
|
||||
|
||||
**v1.1** (Nov 4, 2025)
|
||||
- Added Amazon AI Playbook claims page
|
||||
- Added ChatGPT Features claims page
|
||||
- 15 pages total
|
||||
- Strict image criteria implemented
|
||||
- Comprehensive documentation created
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Learning Resources
|
||||
|
||||
### Understanding GEO
|
||||
- Read: `MIGRATION_SUMMARY.md` → "Why This is Better for GEO"
|
||||
- Compare: Before/After HTML examples
|
||||
|
||||
### Creating Quality Claims
|
||||
- Study: Existing claims pages
|
||||
- Review: "Extract Atomic Claims" in `WORKFLOW.md`
|
||||
- Practice: Create claims from sample articles
|
||||
|
||||
### Image Selection
|
||||
- Read: `CLAIMS_PAGE_GUIDELINES.md`
|
||||
- Review: Approved vs Rejected examples
|
||||
- Visual reference: Existing compliant images in `/public/assets/`
|
||||
|
||||
---
|
||||
|
||||
**Last updated:** 2025-11-04
|
||||
**Maintained by:** Kamil Banc
|
||||
**Status:** ✅ All documentation current and aligned
|
||||
Loading…
Reference in New Issue