pragmatic-docs

Write documentation that respects the reader's time, explains why before how, uses real examples instead of abstract descriptions, and isn't afraid to have an opinion. Inspired by Philip Greenspun's approach: start with the big idea, show real code in context, acknowledge trade-offs honestly, and stop writing before the reader stops reading.

Every document opens with The Big Idea: what this thing is, why it exists, and what problem it solves — in 1–3 paragraphs. If you can't explain why someone should care in three paragraphs, you don't understand the project well enough.

Bad: "This module provides a flexible, extensible, enterprise-grade solution for..." Good: "Users kept asking the same five questions. This tool answers them automatically so maintainers can sleep."

اكتب وثائق مشروع موجزة ومفيدة (READMEs، أدلة، مستندات/) مستوحاة من أسلوب فيليب جرينسبون العملي. يُستخدم عند إنشاء README.md أو تحسينه، أو كتابة مستندات الوحدة النمطية، أو CONTRIBUTING.md، أو تنظيم أي وثائق مشروع لمشاريع البرامج. المصدر: vmvarela/skills.