Documentation Organization Guide

Current Status

The project uses Redocly with sidebars.yaml to control what appears in customer-facing docs.

Customer-Facing Docs (Should be in sidebars.yaml)

All docs currently in sidebars.yaml are appropriate for customers:

Overview section
Quick Start
Deployment
Core Concepts
Guides
API Reference
Tutorials
SDKs & Tools
Examples
Integrations

These new comparison docs should be added to the Overview section in sidebars.yaml:

overview/comparison-cheat-sheet.md - One-page comparison (very valuable for customers)
overview/when-do-you-need-papr.md - Decision guide (helps qualification)
overview/why-papr.md - Detailed comparison (key for evaluation)
overview/diy-stack-comparison.md - Technical deep-dive (for technical evaluators)

Internal Docs (Should NOT be in sidebars.yaml)

These are internal planning/analysis docs and should stay out of customer view:

Root directory internal docs:

AUDIT-ANSWERS.md - Internal audit responses
AUDIT-SUMMARY.md - Internal audit summary
ENTERPRISE-FEEDBACK-ANALYSIS.md - Internal feedback analysis
FINAL-SUMMARY.md - Internal positioning summary
NEW-DOCS-IMPLEMENTATION-GUIDE.md - Internal guide for using docs
PAPR-ADVANTAGES-UPDATE.md - Internal update notes
POSITIONING-UPDATES-SUMMARY.md - Internal positioning notes
QUICK-WINS-COMPLETE.md - Internal task tracking
REDDIT-REFERENCES-REMOVED.md - Internal change log
VIDEO-AUDIO-AUDIT.md - Internal audit
DOCS-ORGANIZATION.md - This file (internal guide)

Keep these internal docs:

Useful for team reference
Document decision-making process
Help with future updates

🤔 Borderline - Decide Based on Use

README.md (root)
- Current: Not in sidebar
- Recommendation: Keep as GitHub README, not in customer docs
- Reason: Redocly has its own landing page
about.md (root)
- Current: Not in sidebar
- Recommendation: Review content, possibly move to Overview section if customer-relevant
changelog.md (root)
- Current: Not in sidebar
- Recommendation: Could add to sidebar as "Changelog" if you maintain public changelog
papr-chat-template.md (root)
- Current: Not in sidebar
- Recommendation: If this is a customer-facing template, move to examples/ or tutorials/

Recommended Actions

1. Update sidebars.yaml - Add New Comparison Docs

Add to the Overview section (after line 19 in current sidebars.yaml):

- group: Overview
  page: overview/index.md
  items:
    - page: overview/predictive-memory.md
      label: Predictive Memory
    - page: overview/unified-graph.md
      label: Unified Graph
    - page: overview/structured-data.md
      label: Structured Data
    # ADD THESE NEW ITEMS:
    - separator: Evaluation & Comparison
    - page: overview/comparison-cheat-sheet.md
      label: Comparison Cheat Sheet
    - page: overview/when-do-you-need-papr.md
      label: When Do You Need Papr?
    - page: overview/why-papr.md
      label: Why Papr
    - page: overview/diy-stack-comparison.md
      label: DIY Stack Comparison
    # EXISTING ITEMS CONTINUE:
    - page: overview/capability-matrix.md
      label: Capability Matrix
    - page: overview/use-cases.md
      label: Use Cases
    - page: overview/decision-tree.md
      label: Decision Tree
    - page: overview/golden-paths.md
      label: Golden Paths
    - page: overview/content-ownership.md
      label: Content Ownership Model

2. Move Internal Docs to Separate Folder

Create an internal/ or .internal/ folder to clearly separate:

mkdir -p internal/planning
mv AUDIT-*.md internal/planning/
mv FINAL-SUMMARY.md internal/planning/
mv NEW-DOCS-IMPLEMENTATION-GUIDE.md internal/planning/
mv PAPR-ADVANTAGES-UPDATE.md internal/planning/
mv POSITIONING-UPDATES-SUMMARY.md internal/planning/
mv QUICK-WINS-COMPLETE.md internal/planning/
mv REDDIT-REFERENCES-REMOVED.md internal/planning/
mv VIDEO-AUDIO-AUDIT.md internal/planning/
mv ENTERPRISE-FEEDBACK-ANALYSIS.md internal/planning/
mv DOCS-ORGANIZATION.md internal/planning/

3. Add .gitignore Rule (Optional)

If you want to keep internal docs out of git:

echo "internal/" >> .gitignore

Or keep them in git but ensure Redocly ignores them (it already does by not being in sidebars.yaml).

4. Review Root-Level Docs

README.md:

Keep as GitHub README
Not needed in Redocly (has its own landing)

about.md:

Review content
If customer-relevant, add to sidebar
If internal, move to internal/

changelog.md:

If maintaining public changelog, add to sidebar
If internal tracking, move to internal/

papr-chat-template.md:

If customer template, move to examples/ or tutorials/
If internal, move to internal/

File Structure Recommendation

memory-dev-docs/
├── internal/                    # Internal docs (not in sidebar)
│   └── planning/
│       ├── AUDIT-ANSWERS.md
│       ├── AUDIT-SUMMARY.md
│       ├── FINAL-SUMMARY.md
│       ├── PAPR-ADVANTAGES-UPDATE.md
│       └── ... (other internal docs)
│
├── overview/                    # Customer-facing overview
│   ├── index.md                ✅ In sidebar
│   ├── comparison-cheat-sheet.md  ⚠️ ADD to sidebar
│   ├── when-do-you-need-papr.md   ⚠️ ADD to sidebar
│   ├── why-papr.md                ⚠️ ADD to sidebar
│   ├── diy-stack-comparison.md    ⚠️ ADD to sidebar
│   └── ... (other overview docs)
│
├── quickstart/                  ✅ In sidebar
├── concepts/                    ✅ In sidebar
├── guides/                      ✅ In sidebar
├── tutorials/                   ✅ In sidebar
├── examples/                    ✅ In sidebar
├── integrations/                ✅ In sidebar
├── sdks/                        ✅ In sidebar
├── deployment/                  ✅ In sidebar
│
├── README.md                    ℹ️ GitHub only (not in sidebar)
├── sidebars.yaml               🔧 Controls customer-facing docs
├── redocly.yaml                🔧 Redocly config
└── ... (other config files)

Verification Checklist

After making changes:

All new comparison docs appear in customer-facing sidebar
All internal planning docs are NOT in sidebar
Internal docs moved to internal/ folder
Redocly build succeeds: npx @redocly/cli build-docs
Preview looks correct: npx @redocly/cli preview-docs
No broken links in customer-facing docs
Navigation flows logically (Overview → Comparison → Quick Start)

Priority Actions

High Priority (Do First)

✅ Add new comparison docs to sidebars.yaml
- These are valuable for customers and should be discoverable
- Add under Overview section with "Evaluation & Comparison" separator

Medium Priority (Do Soon)

✅ Move internal docs to internal/ folder
- Keeps repo organized
- Clear separation of customer vs. internal

Low Priority (Nice to Have)

✅ Review root-level docs (README, about, changelog, papr-chat-template)
- Decide if customer-facing or internal
- Move or add to sidebar accordingly

Testing Customer View

To verify what customers see:

Local preview:
```
npx @redocly/cli preview-docs
```
Open http://localhost:4000 and verify:
- New comparison docs appear in sidebar
- Internal docs do NOT appear
- All links work
Build check:
```
npx @redocly/cli build-docs
```
Verify no errors
Production check:
- After deploying, visit https://platform.papr.ai
- Navigate through sidebar
- Confirm comparison docs are visible
- Confirm internal docs are NOT visible

Notes

Redocly only shows what's in sidebars.yaml - Files not in sidebar won't appear in customer docs
Root-level .md files are typically for GitHub, not Redocly
Internal docs can stay in repo (useful for team) but should be clearly separated
New comparison docs are high-value for customers and should be prominent in Overview section