How to Write a Review

These are working notes, not tutorials. A review answers should we keep using this? and what did we actually learn? — not how does this work?

Structure

Goals

What we were trying to accomplish when we adopted this dependency. Be specific about the problem we needed solved, not the category of tool.

Effectiveness

How well the tool achieved those goals in practice. Would we choose it again?

What made it effective

Specific design decisions, features, or qualities that made it work. These are the things worth noticing.

Bonus utility

Value we discovered after adoption that we didn't plan for. Side-effects we kept.

Friction / pain points / surprises

Real problems encountered. Configuration traps, API design failures, failure modes hit in production. These are the most valuable entries — the things you'd tell a colleague before they start.

Tone

• Write from experience. If we haven't encountered it, don't include it.
• Be specific. "The API is bad" is not useful. "The /search endpoint returns HTML — use /query" is useful.
• Don't hedge. Write what actually happened.
• No introductions, definitions, or "this is a tool that...". We know what it is.
• Keep installation and usage notes only if they encode a real lesson (e.g. a non-obvious flag, a broken default). Don't document what the README already says.

What does NOT belong

• Tutorials or getting-started guides
• API reference tables (unless a specific entry encodes a lesson)
• Background on what the tool does (reader already knows)
• Future plans or wishlist items unless relevant to the review verdict