Readme review

[strawgate]

We need to do a line-by-line review of our readme, agents and developing docs for inaccuracies that need to be fixed prior to release

[claude]

Claude finished @strawgate's task —— View job

---

Documentation Review Complete ✓

Conducted a comprehensive line-by-line review of all documentation files for inaccuracies prior to release.

---

Recommendation

The documentation is in very good shape overall. A previous review in issue #136 already caught major issues. I found only 2 minor inaccuracies that should be corrected before release:

1. README.md line 138: Variable name should be key_value not memory_store (already fixed in docs: fix documentation issues #141)
2. AGENTS.md line 191: Missing DataclassAdapter from the adapters list

---

Findings

✅ README.md (415 lines) - Mostly Accurate

Verified Claims:

• ✅ License is Apache 2.0 (confirmed in LICENSE file and pyproject.toml)
• ✅ All listed stores exist in codebase (14 stores verified)
• ✅ All listed wrappers exist (17 wrappers verified)
• ✅ All listed adapters exist (DataclassAdapter, PydanticAdapter, RaiseOnMissingAdapter)
• ✅ Code examples use correct import paths and API signatures
• ✅ Installation instructions match pyproject.toml extras
• ✅ Protocol method signatures are accurate
• ✅ FastMCP reference is accurate (real project using py-key-value)

Minor Issue:

• ⚠️ Line 138 variable naming in example was already fixed in PR docs: fix documentation issues #141 (merged)

Notes:

• Version numbers (0.2.8) are current and will be bumped separately for release
• All store classifications (Local, Secret, Distributed) are accurate
• Stability markings (Stable/Unstable/Preview) match current state

✅ AGENTS.md (247 lines) - One Missing Adapter

Verified Claims:

• ✅ All development workflow commands are correct (make precommit, make codegen, etc.)
• ✅ Architecture description matches codebase structure
• ✅ Code style settings match pyproject.toml (Ruff, Basedpyright, line length 140)
• ✅ Makefile commands reference is accurate
• ✅ Python version requirement (3.10+) is correct
• ✅ Markdown line length (80 chars) is accurate per .markdownlint.jsonc

Missing Item:

• ⚠️ Line 188-192: Adapters list mentions PydanticAdapter and RaiseOnMissingAdapter but omits DataclassAdapter (added in PR Add DataclassAdapter using Pydantic TypeAdapter #147, merged Oct 28)

Accurate Sections:

• File paths for stores, wrappers, adapters
• ManagedEntry explanation
• Sync codegen workflow
• CI/CD job descriptions
• Version management commands

✅ DEVELOPING.md (136 lines) - Fully Accurate

Verified Claims:

• ✅ Prerequisites match devcontainer setup
• ✅ Python version (3.10) matches pyproject.toml
• ✅ All make commands exist and work as documented
• ✅ Codegen notes match actual workflow
• ✅ Project layout paths are correct
• ✅ CI workflow explanation matches .github/workflows/test.yml

No Issues Found - This file is completely accurate

✅ Package-Level READMEs - Simple References

All four package READMEs are minimal files that correctly reference the main README:

• ✅ key-value-aio/README.md
• ✅ key-value-sync/README.md
• ✅ key-value-shared/README.md
• ✅ key-value-shared-test/README.md

No Issues Found

---

Detailed Action Plan

To fix the one remaining inaccuracy:

Fix Missing DataclassAdapter in AGENTS.md:

# Current (lines 188-192)
Key adapters:

- `PydanticAdapter` - Type-safe Pydantic model storage
- `RaiseOnMissingAdapter` - Raise exceptions for missing keys

# Should be:
Key adapters:

- `DataclassAdapter` - Type-safe dataclass storage with Pydantic validation
- `PydanticAdapter` - Type-safe Pydantic model storage  
- `RaiseOnMissingAdapter` - Raise exceptions for missing keys

---

Related Items

Related Issues and Pull Requests

Repository	Issue/PR	Relevance
strawgate/py-key-value	#136: In-depth review of Readme, Agents and Developing	Previous documentation review that fixed variable names and license statement (closed Oct 27)
strawgate/py-key-value	#141: docs: fix documentation issues	PR that fixed the README.md line 138 variable name issue (merged Oct 27)
strawgate/py-key-value	#124: More detailed documentation	MkDocs documentation effort in progress (open)
strawgate/py-key-value	#147: Add DataclassAdapter	Added DataclassAdapter but AGENTS.md wasn't updated (merged Oct 28)

Related Files

Repository	File	Relevance
strawgate/py-key-value	LICENSE	Confirms Apache 2.0 license mentioned in README
strawgate/py-key-value	pyproject.toml	Confirms license, Python version, and package structure
strawgate/py-key-value	Makefile	Confirms all make commands documented in AGENTS.md
strawgate/py-key-value	key-value-aio/src/key_value/aio/stores/	Confirms all 14 stores mentioned in README exist
strawgate/py-key-value	key-value-aio/src/key_value/aio/wrappers/	Confirms all 17 wrappers mentioned in README exist
strawgate/py-key-value	key-value-aio/src/key_value/aio/adapters/dataclass/adapter.py	DataclassAdapter exists but missing from AGENTS.md

---

Problems Encountered During Investigation

None - All investigation tools and resources were accessible.

---

[strawgate]

@claude Now that we have /docs available, should we make index.md our readme and maybe just move it into our docs folder on publish or something? what do you think?

feels weird having the same info in our readme as in our index.md

[claude]

Claude finished @strawgate's task —— View job

---

Documentation Structure Analysis & Recommendation

• Read README.md and docs/index.md to assess duplication
• Analyze differences and identify duplication issues
• Research best practices for README vs docs coordination
• Provide recommendation with pros/cons

---

Current State Analysis

After reviewing both files, here's what I found:

README.md (423 lines)

• Comprehensive, production-ready documentation
• Contains detailed examples, all store/wrapper/adapter listings
• Includes installation instructions, advanced patterns, protocol definitions
• Framework author value proposition with FastMCP example
• Essentially a complete standalone guide

docs/index.md (89 lines)

• Brief landing page style
• High-level overview with quick links to other docs pages
• Delegates details to getting-started.md, wrappers.md, adapters.md
• Much more concise and navigation-focused

Key Difference: The README is comprehensive (everything in one place), while docs/index.md is a landing page that routes to specialized pages. This is actually good separation - they serve different purposes.

---

Recommendation: Keep Both, But Differentiate Them

I do not recommend making index.md your README. Here's why:

✅ Current Approach Benefits

1. README serves GitHub visitors: When someone lands on your GitHub repo, they want comprehensive info immediately. Your current README excels at this - it's a complete reference that answers "what is this?" and "how do I use it?" without clicking away.

2. docs/index.md serves MkDocs visitors: People who navigate to your documentation site expect a landing page with navigation, not a wall of text. Your current index.md is perfect for this.

3. Different contexts, different needs:

   • GitHub: One-page reference (README)
   • Docs site: Multi-page navigation (index.md + sub-pages)

❌ Why Syncing Would Be Problematic

1. Context mismatch: README links to GitHub content (issues, PRs), while docs/index.md should link to other doc pages
2. Length issues: Your README is too long for a landing page, but perfect for GitHub
3. Maintenance complexity: Syncing introduces build complexity and potential sync failures
4. SEO/discoverability: READMEs and documentation homepages have different SEO patterns

---

Alternative Approach: Reduce Duplication Strategically

If the duplication bothers you, here are targeted solutions:

Option 1: Thin README (Redirect to Docs) ⭐ Recommended

Convert README.md to a brief overview that points to full docs:

# py-key-value

A pluggable Python framework for key-value stores with support for multiple 
backends, TTL handling, and type safety.

**[📚 Full Documentation](https://strawgate.github.io/py-key-value/)**

## Quick Start
[Brief installation + single example]

## Features
- Multiple backends (Redis, DynamoDB, MongoDB, etc.)
- TTL support
- Type-safe protocols
- [etc.]

## Installation
[pip install commands]

For complete documentation, examples, and API reference, visit 
**[strawgate.github.io/py-key-value](https://strawgate.github.io/py-key-value/)**

Pros:

• Minimal duplication
• GitHub visitors still get overview + quick start
• Docs site becomes single source of truth
• Easy maintenance

Cons:

• GitHub README less comprehensive (some may prefer everything there)
• Requires users to click through for details

Option 2: Sync from README to Docs (Not Recommended)

You mentioned syncing index.md → README. I'd suggest the reverse if you must sync:

• Keep README as source of truth
• Generate docs/index.md from README during publish
• Use a script to extract relevant sections

Why this direction?: GitHub is likely your primary discovery point (more traffic than docs site initially), so README should be authoritative.

Cons:

• Added build complexity
• Risk of sync failures breaking docs
• Harder to maintain doc-specific content

Option 3: Keep Current Structure (Also Recommended ✅)

Your current setup isn't actually problematic:

• README: Comprehensive standalone guide (good for PyPI, GitHub)
• docs/index.md: Landing page with navigation (good for MkDocs)
• docs/getting-started.md: Detailed tutorial (good for learners)

The "duplication" is minimal - they're different views of the same content. Installation instructions appearing in both places is totally fine and expected.

---

My Specific Recommendation

Go with Option 1 (Thin README) if:

• You want docs site to be authoritative
• You're comfortable directing people away from GitHub README
• You want minimal maintenance burden

Go with Option 3 (Keep current) if:

• You value comprehensive GitHub README (I do!)
• You're okay with some content overlap
• You want users to get full info without leaving GitHub

I'd personally choose Option 3 (keep current structure) because:

1. Your README is excellent and serves GitHub visitors well
2. The duplication is actually quite minimal (installation, quick example)
3. Most successful OSS projects have comprehensive READMEs
4. It's zero maintenance overhead vs. sync complexity

---

What Others Do

• Rich (by @willmcgugan): Comprehensive README, docs site has similar but expanded content
• FastAPI: Minimal README that redirects to docs
• Requests: Moderate README with basics, detailed docs site
• Django: Thin README, comprehensive docs

All approaches work - it depends on your priorities. For a library like yours (framework-oriented, needs examples), I lean toward comprehensive README.

---

Action Items

If you want to proceed:

Option 1 (Thin README):

• Create new minimal README.md
• Ensure docs/getting-started.md has all the content from old README
• Update pyproject.toml readme field if needed

Option 3 (Keep Current):

• No action needed
• Maybe add cross-links (README → docs site, docs → GitHub)

Let me know which direction you prefer and I can help implement it!

---

[strawgate]

@claude let's thin out the readme a little by moving the tables of wrappers, adapters and stores into the docs and reducing the content in readme while still ensuring the readme gives a good overview before linking to the more specific docs.

[claude]

Claude finished @strawgate's task —— View job • claude/issue-172-20251029-0224 • Create PR ➔

---

Thinning Out README ✓

Successfully moved detailed tables from README to docs while keeping a good overview!

Summary of Changes

Created:

• docs/stores.md - Comprehensive store documentation with:
  • Store categories (Local, Secret, Distributed)
  • Stability levels explanation
  • Detailed documentation for all 14 stores
  • Installation guides and examples
  • "Choosing a Store" guidance for different use cases

Enhanced:

• docs/wrappers.md - Added summary table with links to all 17 wrappers
• docs/adapters.md - Added summary table and DataclassAdapter documentation
• mkdocs.yml - Added stores.md to navigation

Updated README.md:

• Replaced detailed store tables (40+ lines) with concise 3-category overview
• Replaced adapter table with bullet points and link
• Replaced wrapper table with categorized list and link
• Added prominent links to full documentation
• Reduced from 423 to ~350 lines while maintaining clarity

Key Improvements

1. Better Maintainability: Tables only exist in one place (docs)
2. Clearer Navigation: README provides overview, docs have details
3. More Context: Store docs include use cases, characteristics, and guidance
4. Complete Coverage: Added missing DataclassAdapter documentation

Tasks

• Generate project summary and gather context
• Read current README.md structure
• Read existing docs pages (wrappers.md, adapters.md, stores)
• Create docs/stores.md with comprehensive store information
• Enhance docs/wrappers.md with summary table
• Enhance docs/adapters.md with summary table and DataclassAdapter
• Update README to be concise with links to detailed docs
• Update mkdocs.yml navigation to include stores.md
• Commit and push changes

---