مخاطبِ داک را کجا میفهمم؟

سؤالِ «این برای کیست؟» را قبل از نوشتن جواب بده و در همان بندِ اول بنویس: "This guide is for new backend devs joining the payments team. If you're looking for the API reference, see /docs/api." داکِ بیمخاطب، همهکاره میشود و همهکاره یعنی هیچکاره. قاعدهٔ عملی: یک داک، یک مخاطب، یک کار — و لینک برای بقیه.

زبانم را داکنویسی بهتر میکند یا داکخوانی؟

هر دو، اما با نسبتِ متفاوت: بخوان تا الگو ببینی (READMEهای محبوبِ گیتهاب را بخوان — ساختارشان همین درس است) و بنویس تا عضله بسازی. تمرینِ عملی: پروژهٔ شخصیات را با قالبِ امروز README کن و به یک دوستِ فنی بده — اگر بدونِ سوالِ تو راه افتاد، داکِ تو سبز است. نوشتنِ برای «خوانندهٔ واقعی»، سریعترین معلمِ سادهنویسی است.

درس ۵۹ از ۹۰ · مستندسازی؛ README، کامنت و داکِ دور

مستندسازی، دومین مهارتِ «پنهان اما ارزیابی‌شده» فنی است: کسی ا overt شاخص نمی‌گذارد، اما داکِ خوب، سال‌ها بعدِ رفتنِ تو هم به تو اعتبار می‌دهد — و داکِ بد، هر روز از وقتِ همه را می‌خورَد. برای زبانِ دوم، نکتهٔ طلایی این است که نوشتارِ فنی از هر متنی ساده‌تر است: جمله‌ها کوتاه‌اند، لحن امری است، و واژه‌ها تکرار می‌شوند.

این درس مقدمهٔ فنی است؛ نسخهٔ حرفه‌ای‌تر (RFC و پروپوزال) در فاز ۵ می‌آید. قالب‌های امروز را در ریپوی خودت امتحان کن — اولین READMEای که با همین درس بنویسی، بهترین داکِ عمرت خواهد بود.

README؛ در چهار بلاک

قالبِ استانداردِ README: ۱) یک جمله: این چیست؟ "A tiny Python library for turning CSVs into charts." ۲) Quickstart: سه فرمانِ تا نتیجه: pip install x ← import x ← خروجی. ۳) چرا این؟ یک بلاکِ تفاوت: "No dependencies. Works offline. 10x faster than Y for small files." ۴) Contributing + License. قاعده‌های زبانی: جمله‌های زیرِ ۲۰ کلمه، دوم‌شخص (you), فرمان‌ها در code block با ‎، و بدونِ تبلیغِ اضافی — داکِ خوب، خودش را با «کارکردن» می‌فروشد نه با صفت.

## Quickstart 1. `pip install upword-charts` 2. `import upword_charts as uc` 3. `uc.from_csv("data.csv").save("out.png")` That's it — no config file, no account.شروعِ سریع — همین؛ نه فایلِ کانفیگ، نه اکانت.

کامنت؛ «چرا» نه «چه»

کامنتِ بد: i++; // add one to i (کد خودش می‌گوید). کامنتِ خوب، سه چیز را می‌گوید: ۱) چرا: // Retry 3x: the payment API drops ~0.1% of requests under load. ۲) هشدار: // NOTE: changing this breaks the mobile client (v2). Ask the mobile team first. ۳) لینکِ منشأ: // See ADR-12 for why we chose gRPC over REST here. — و برای کدِ موقت: // TODO(alip): remove after the 2026-02 migration. Tracking in TICKET-841. قالبِ TODO با اسم و تاریخ و شماره، کامنتِ زنده می‌سازد نه سنگ‌قبرِ فراموشی.

داکِ تصمیم و داکِ دور؛ ADR و postmortem

ADR (Architecture Decision Record): یک تصمیمِ فنی در چهار بند: Context (وضعیت), Decision (تصمیم), Consequences (پیامدها), Alternatives (بدیل‌های ردشده). نمونه: "We will use Postgres for the event store. Context: team knows it, ops tooling exists. Consequences: no replay performance tuning like Kafka; we accept this for now." و postmortem (بازبینیِ حادثه) با بی‌اتهام‌ترین قالبِ دنیا: "What happened / Impact / Timeline / Root cause / Action items" — جملهٔ کلیدی: "X caused Y" نهِ "Ali caused Y" — در داکِ سالم، عاملیت با سیستم است نه با آدم.

Root cause: the retry logic created duplicate charges when the response was slow but successful. Action item: idempotency keys on all payment endpoints (owner: payments team, due: next sprint).ریشه: منطقِ retry موقعِ کندی، پرداختِ تکراری می‌ساخت. اقدام: کلیدِ idempotency روی همهٔ endpointهای پرداخت (مسئول: تیمِ پرداخت، ضرب‌الاجل: اسپرینتِ بعد).

گرامرِ عمیق‌تر: زبانِ دستورالعمل — امریِ خنثی و مخاطبِ you

داک، زبانِ امریِ بی‌فاعلِ دوم‌شخص است: Run the script. (اسکریپت را اجرا کن) · Do not edit this file directly. (این فایل را مستقیم ویرایش نکن) — بدونِ «you should» و بدونِ لطفِ اضافی. برای هشدار: WARNING: / NOTE: / TIP: — سه برچسبِ استاندارد. و برای گام‌ها: First… Next… Finally یا شماره. جملهٔ کوتاهِ داک زیرِ ۲۰ کلمه؛ مخاطبِ داک همیشه you — حتی اگر داک را «ما» نوشته باشند، خواننده «you» است. برای چیزهای اختیاری: Optionally, you can… — برچسبِ درست، همیشه مؤدب‌تر از حذف‌کردن است.

## Setup 1. Clone the repo and copy `.env.example` to `.env`. 2. Run `docker compose up`. 3. Open `localhost:3000` — you should see the demo dashboard. NOTE: the seed data is fake by design. Do not use real customer info locally.راه‌اندازی — … نکته: داده‌های اولیه عمداً فیک‌اند. اطلاعاتِ واقعیِ مشتری را لوکال استفاده نکنید.

گفتگو: رترویِ داک — «داکِ ما چه احساسی دارد؟»

Lead: Retro item: our onboarding docs. New people keep asking the same five questions. — You: Because the answers live in five different places. I counted.لید: بندِ رترو: داک‌های onboarding ما. آدم‌های جدید همون پنج سوال رو می‌پرسن. — تو: چون جواب‌ها تو پنج جای مختلفه. شمردم.

Lead: Proposal? — You: One page, five answers, one owner — me, this sprint. "New joiner FAQ" with links to the deep docs.لید: پیشنهاد؟ — تو: یه صفحه، پنج جواب، یه مالک — من، همین اسپرینت. «سوالاتِ پرتکرارِ تازه‌وارد» با لینک به داک‌های عمیق.

Lead: Love it — small, owned, done. — You: And the experiment: we track the five questions for two weeks. If they stop, the doc worked; if they move, the doc learns.لید: عالیه — کوچیک، مالک‌دار، تمام‌شده. — تو: و آزمایش: دو هفته همون پنج سوال رو رصد می‌کنیم. اگه قطع شدن، داک جواب داد؛ اگه جابه‌جا شدن، داک یاد می‌گیره.

اشتباه‌های رایجِ فارسی‌زبان‌ها در همین درس

این بخش را با یک قرارداد بخوان: هر ❌ یعنی «مغزِ فارسی‌زبانت این را می‌سازد و طبیعی است»، و هر ✅ یعنی «این همان چیزی است که گیرندهٔ انگلیسی‌زبان می‌شنود». خطاها اثرِ مستقیمِ ترجمهٔ ذهنیِ فارسی به انگلیسی‌اند؛ با هر جفت بلند تکرار کن تا شکلِ درست در گوشت نشست کند.

❌ You should run the script after you copied the config file.❌ داک جایِ ادبِ فارسیِ «بهتر است اجرا کنید» نیست؛ امریِ خنثیِ دوم‌شخص استانداردِ داک است — کوتاهی در داک بی‌احترامی نیست، احترام به وقتِ خواننده است. should باید برود.

✅ Run the script after copying the config file.✅ شکل درست را دو بار بلند بگو؛ حالا یک بار در یک جملهٔ خودت.

❌ For install the app, run this command.❌ «برایِ نصب» مستقیم با For + فعل ترجمه می‌شود؛ انگلیسیِ هدف to + مصدر می‌سازد. for فقط اسم می‌گیرد (for the setup) — فعل را نمی‌پذیرد.

✅ To install the app, run this command.✅ شکل درست را دو بار بلند بگو؛ حالا یک بار در یک جملهٔ خودت.

❌ It is necessary that you do not edit this file.❌ ترجمهٔ نامهٔ اداریِ «لازم است که…» رؤیای هشدار را می‌خواباند؛ هشدارِ داک با Do not + برچسبِ WARNING دو کلمه است و خواننده را بیدار می‌کند.

✅ WARNING: do not edit this file directly.✅ شکل درست را دو بار بلند بگو؛ حالا یک بار در یک جملهٔ خودت.

تمرین‌های این درس — چهار قدم، بی‌عجله

داک‌نویسی، تمرینِ قیچی است؛ چهار تمرین را با برش‌های دقیق و بلند اجرا کن، بعد پاسخ‌ها را باز کن.

این جمله را امریِ داک کن: «You should probably copy .env.example to .env before you start.»
غلطِ معروفِ for را اصلاح کن: «For run the tests, use this command.»
برچسب را انتخاب کن و دلیلش را بگو: «داده‌های اولیه عمداً فیک‌اند» — WARNING یا NOTE؟
سه گامِ راه‌اندازی را شماره‌دار بنویس: clone کردنِ ریپو، اجرای docker compose، بازکردنِ localhost — هر گام یک فعلِ امری.

پاسخ تمرین‌ها — اول خودت جواب بده، بعد باز کن

پاسخ تمرین ۱

"Copy .env.example to .env before you start." — should probably حذف شد؛ امری + ترتیبِ گام. داکِ خوب مثل کامنتِ گیت است: کوتاه و قابلِ اجرا.

پاسخ تمرین ۲

"To run the tests, use this command." هدف با to + فعل: To run. for فقط اسم می‌گیرد — for the test run می‌شود، for run the tests هرگز.

پاسخ تمرین ۳

NOTE — "NOTE: the seed data is fake by design." WARNING برای فاجعه است و NOTE برای نکتهٔ غیرمنتظرهٔ بی‌خطر؛ برچسبِ اشتباه، آژیرِ بی‌اعتبار می‌سازد و آژیرِ بی‌اعتبار، آژیرِ مرده است.

پاسخ تمرین ۴

نمونه: "1. Clone the repo. 2. Run docker compose up. 3. Open localhost:3000." — سه گام، سه فعلِ امری، هر گام زیرِ بیست کلمه؛ مقدمه لازم نیست.

چالشِ امروز

🎯 برای کاری که امروز انجام دادی یک داکِ سه‌گامی بنویس — امریِ خنثی، بی‌مقدمه — و در ویکی یا فولدرِ مستنداتِ تیم بگذارش.

نکات مکالمهٔ واقعی که کتاب‌ها کم می‌گویند

داک را با سوال بساز — هر بندِ داک، جوابِ یک سوالِ واقعی است — سوال‌های تکراریِ تیم، فهرستِ فصل‌های داکِ بعدی‌ات‌اند.
یک صفحه، یک مالک، یک تاریخ — داکِ بی‌مالک، مردهٔ متولد‌نشده است؛ اسمِ مالک و تاریخِ آخرین بازبینی بالای هر صفحه.
امریِ خنثی بنویس — «Run…» به‌جایِ «You should probably run…» — کوتاهیِ داک، احترام به وقتِ خواننده است نه خشکی.

🔑 جمع‌بندی این درس

README چهاربلاک: چیست (یک جمله) + Quickstart (سه فرمان) + چرا (تفاوت) + Contributing. کامنت فقط «چرا/هشدار/لینک» — هرگز «چه» — و TODO با اسم و تاریخ و تیکت. ADR: Context/Decision/Consequences/Alternatives; postmortem بی‌اتهام: "X caused Y". داک، فقط نوشتن نیست؛ نگه‌داشتنِ دانشِ تیم است.

مستندسازی؛ README، کامنت و داکِ دور