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