case-study-README.md

README rewrite: node-cacheman

Small open source project, ~800 stars. Maintainer asked for help because people kept opening issues about basic usage.

Before

The original README:

# cacheman

A caching library

## Installation
npm install cacheman

## Usage
const cache = require('cacheman')
cache.set('key', 'value')
cache.get('key')

more methods available see source code

## Options
you can pass options

## License
MIT

Problems:

• No explanation what it actually does
• "see source code" = people won't
• No error handling examples
• Missing common use cases

After

# cacheman

In-memory cache for Node.js with TTL support. Stores key-value pairs, auto-expires them, uses LRU eviction when full.

## Install

npm install cacheman

## Basic usage

const cache = require('cacheman');

// Store for 5 minutes
await cache.set('user:123', userData, 300);

// Retrieve
const user = await cache.get('user:123');
// Returns null if expired or not found

// Delete
await cache.del('user:123');

## With Express

const cache = require('cacheman');

app.get('/users/:id', async (req, res) => {
  const key = `user:${req.params.id}`;
  
  // Try cache first
  let user = await cache.get(key);
  
  if (!user) {
    // Cache miss - get from DB
    user = await db.users.find(req.params.id);
    await cache.set(key, user, 600); // 10 min
  }
  
  res.json(user);
});

## Options

const cache = require('cacheman')({
  max: 1000,        // max items (default: unlimited)
  ttl: 3600,        // default TTL in seconds
  checkPeriod: 60   // cleanup interval
});

## API

| Method | Description |
|--------|-------------|
| set(key, value, ttl?) | Store value |
| get(key) | Retrieve or null |
| del(key) | Delete |
| clear() | Delete all |
| keys() | List all keys |
| has(key) | Check if exists |

## Common patterns

Invalidate on update:

await db.users.update(id, data);
await cache.del(`user:${id}`);

Cache-aside with fallback:

async function getUser(id) {
  const cached = await cache.get(`user:${id}`);
  if (cached) return cached;
  
  const user = await db.users.find(id);
  if (user) {
    await cache.set(`user:${id}`, user, 600);
  }
  return user;
}

Results

After 2 months:

• "How to use" issues: 12 → 2
• npm weekly downloads: went from ~1.8k to ~4.3k
• Stars: picked up maybe 150 new ones

The maintainer said most issues now are actual bugs/features instead of "how do I do X" questions.

---

Not every rewrite goes viral. But good docs reduce support burden and help people actually use the thing.