# فصل ۰۳ — مستنداتی که کهنه نمی‌شود

<div dir="rtl">

# فصل ۰۳ — مستنداتی که کهنه نمی‌شود

## در این فصل چه یاد می‌گیری

یک `README` می‌سازیم با شش دستورِ مستندشده — از همان‌هایی که در هر پروژه‌ای هست و همه فرض می‌کنند کار می‌کنند. بعد تستی می‌نویسیم که آن‌ها را از داخلِ متن بیرون می‌کشد و در یک نسخهٔ تازهٔ پروژه اجرا می‌کند.

**از شش دستور، یکی کار می‌کند.**

بعد درستش می‌کنیم و می‌شود **هفت از هفت**. و همان تست را به دروازهٔ فصلِ قبل وصل می‌کنیم: عوض کردنِ نامِ یک گزینه در کد، **دو دستورِ مستندشده را قرمز می‌کند** — بدونِ اینکه کسی `README` را باز کرده باشد.

در آخر سه تصمیم‌نامه می‌نویسیم و هر کدام را با یک **نگهبانِ اجراشدنی** می‌سنجیم. یکی سبز است، یکی **قرمز** — یعنی تصمیم نوشته شده و سامانه به آن عمل نمی‌کند — و یکی اصلاً نگهبان ندارد.

![دفترچهٔ راهنمایی که هر صفحه‌اش به یک اهرمِ واقعیِ دستگاه وصل است](/lesson-assets/t6-s03-docs-that-survive/prompt/01-image-manual-wired-to-levers.png)

آخر این فصل می‌توانی:

- دستورهای یک `README` را استخراج و در نسخهٔ تازهٔ پروژه اجرا کنی
- سه خانوادهٔ خرابیِ مستندات را از هم جدا کنی: غلط، ناقص، و کدی که مستند را از کار انداخته
- مستند را به همان دروازهٔ خودکارِ کد وصل کنی
- تصمیم‌نامه‌ای بنویسی که نگهبانِ اجراشدنی دارد

## قبل از شروع

**از فصلِ ۲ همین ترم:** دروازه‌ای که با کدِ خروج جواب می‌دهد. مستندِ اجراشدنی دقیقاً همان قرارداد را دارد.

**از ترمِ ۳ فصلِ ۷ و ترمِ ۴ فصلِ ۶:** دو تصمیمی که در بخشِ ۵ به‌شکلِ تصمیم‌نامه می‌نویسیم، با همان عددهایی که آنجا اندازه گرفتیم.

> 💡 **نکته:** همهٔ دستورهای این فصل `python` هستند، نه فرمانِ پوسته. دلیلش قیدِ دوره است — یک نوت‌بوک باید روی هر سیستمی یک‌جور اجرا شود، و فرمانِ پوسته این را تضمین نمی‌کند. **قاعده‌اش عوض نمی‌شود: دستورِ مستندشده باید اجراشدنی باشد.**

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/darbast/term-6-team-and-delivery/session-03-docs-that-survive.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

</div>

| اجرا | زمانِ تقریبی |
|---|---|
| کلِ نوت‌بوک روی CPU | حدودِ یک دقیقه |
| GPU | لازم نیست |

<div dir="rtl">

## ۱. پروژه، همان‌طور که واقعاً روی دیسک است

هفت فایلِ کوچک. هیچ‌کدام موضوعِ درس نیستند؛ فقط باید واقعی باشند و واقعاً اجرا شوند.

</div>

```python
import json
import re
import shlex

SOURCE = WORK / "source"
FILES = {
    "sample.json": None,                       # پایین‌تر پر می‌شود
    "fetch.py": '"""fetch.py — دادهٔ خام را از نمونهٔ همراهِ مخزن می‌سازد."""\n'
                "import json, pathlib\n\n"
                'rows = json.load(open("sample.json", encoding="utf-8"))\n'
                'pathlib.Path("raw").mkdir(exist_ok=True)\n'
                'json.dump(rows, open("raw/tickets.json", "w", encoding="utf-8"),'
                " ensure_ascii=False)\n"
                'print("raw/tickets.json ساخته شد:", len(rows), "ردیف")\n',
    "prepare.py": '"""prepare.py — پاک‌سازی و ذخیره در work/."""\n'
                  "import json, pathlib\n\n"
                  'rows = json.load(open("raw/tickets.json", encoding="utf-8"))\n'
                  "for row in rows:\n"
                  '    row["text"] = " ".join(row["text"].replace("ي", "ی")'
                  '.replace("ك", "ک").split())\n'
                  'pathlib.Path("work").mkdir(exist_ok=True)\n'
                  'json.dump(rows, open("work/clean.json", "w", encoding="utf-8"),'
                  " ensure_ascii=False)\n"
                  'print("work/clean.json ساخته شد:", len(rows), "ردیف")\n',
    "schema_check.py": '"""schema_check.py — قراردادِ ستون‌ها روی نمونهٔ همراهِ مخزن."""\n'
                       "import json\n\n"
                       'REQUIRED = ("ticket_id", "week", "category", "text", "escalated")\n'
                       'rows = json.load(open("sample.json", encoding="utf-8"))\n'
                       "missing = sorted(set(REQUIRED) - set(rows[0]))\n"
                       'assert not missing, f"ستونِ گم‌شده: {missing}"\n'
                       'print("قرارداد سالم است:", len(rows), "ردیف")\n',
    "train.py": '"""train.py — یک مدلِ شمارشیِ ساده روی داده‌های تا هفتهٔ upto."""\n'
                "import argparse, collections, json, pathlib\n\n"
                "parser = argparse.ArgumentParser()\n"
                'parser.add_argument("--upto", type=int, required=True)\n'
                "args = parser.parse_args()\n"
                'rows = json.load(open("work/clean.json", encoding="utf-8"))\n'
                'train = [r for r in rows if r["week"] < args.upto]\n'
                "score = collections.Counter()\n"
                "for row in train:\n"
                '    for word in set(row["text"].split()):\n'
                '        score[word] += 1 if row["escalated"] else -1\n'
                'pathlib.Path("models").mkdir(exist_ok=True)\n'
                'json.dump(dict(score), open("models/model.json", "w", encoding="utf-8"),'
                " ensure_ascii=False)\n"
                'print("models/model.json ساخته شد از", len(train), "ردیف")\n',
    "evaluate.py": '"""evaluate.py — دقتِ مدل روی هفته‌های بعدی."""\n'
                   "import json\n\n"
                   'model = json.load(open("models/model.json", encoding="utf-8"))\n'
                   'rows = json.load(open("work/clean.json", encoding="utf-8"))\n'
                   'test = [r for r in rows if r["week"] >= 18]\n'
                   "hit = sum((sum(model.get(w, 0) for w in r[\"text\"].split()) > 0)\n"
                   '          == bool(r["escalated"]) for r in test)\n'
                   'print(f"دقت روی {len(test)} ردیفِ آینده: {hit / len(test):.4f}")\n',
    "report.py": '"""report.py — گزارشِ کوتاهِ اجرا."""\n'
                 "import argparse, json\n\n"
                 "parser = argparse.ArgumentParser()\n"
                 'parser.add_argument("--out", required=True)\n'
                 "args = parser.parse_args()\n"
                 'rows = json.load(open("work/clean.json", encoding="utf-8"))\n'
                 'open(args.out, "w", encoding="utf-8").write(f"ردیف: {len(rows)}\\n")\n'
                 'print("گزارش نوشته شد:", args.out)\n',
    "scripts/lint.py": '"""lint.py — هر فایلِ پایتونِ پروژه باید docstring داشته باشد."""\n'
                       "import pathlib\n\n"
                       'bad = [p.name for p in sorted(pathlib.Path(".").glob("*.py"))\n'
                       '       if not p.read_text(encoding="utf-8").startswith(\'"""\')]\n'
                       'assert not bad, f"بدونِ docstring: {bad}"\n'
                       'print("همهٔ فایل‌ها docstring دارند")\n',
}
FILES["sample.json"] = json.dumps(TICKETS, ensure_ascii=False)
for name, text in FILES.items():
    write(SOURCE / name, text)
print("پروژه ساخته شد:", len(FILES), "فایل")
```

```text
پروژه ساخته شد: 8 فایل
```

<div dir="rtl">

## ۲. `README`ی که کسی امتحانش نکرده

حالا مستند. **این `README` دروغ نمی‌گوید؛ روی ماشینِ نویسنده‌اش واقعاً کار می‌کرده.** مسئله همین است.

</div>

```python
TICKS = "`" * 3                                # سه‌تایی‌های markdown، بدونِ درگیریِ نقلِ‌قول


def as_readme(steps):
    """همان `README`ی که در مخزن می‌نشیند: هر دستور داخلِ بلوکِ کدِ خودش."""
    blocks = "\n\n".join(f"{TICKS}bash\n{step}\n{TICKS}" for step in steps)
    return "# خطِ دسته‌بندیِ تیکت\n\n## اجرا\n\n" + blocks + "\n"


README_BROKEN = as_readme([
    "python prepare.py",
    "python schema_check.py",
    "python train.py --weeks 18",
    "python evaluate.py",
    "python report.py --out out/report.md",
    "python tools/lint.py",
])
write(SOURCE / "README.md", README_BROKEN)
BASH_BLOCK = re.compile(TICKS + r"bash\n(.*?)" + TICKS, re.S)


def commands(readme):
    """هر خطِ اجرایی داخلِ بلوک‌های bash، به ترتیبِ متن."""
    return [line.strip() for block in BASH_BLOCK.findall(readme)
            for line in block.split("\n") if line.strip().startswith("python ")]


def fresh_checkout():
    """یک نسخهٔ تازه از پروژه، مثلِ کسی که همین حالا clone کرده."""
    fresh = WORK / "fresh"
    shutil.rmtree(fresh, ignore_errors=True)
    shutil.copytree(SOURCE, fresh)
    return fresh


def run_readme(readme):
    """هر دستورِ مستندشده را در یک نسخهٔ تازه اجرا می‌کند و نتیجه‌اش را برمی‌گرداند."""
    fresh = fresh_checkout()
    write(fresh / "README.md", readme)
    out = []
    for command in commands(readme):
        parts = shlex.split(command)[1:]
        if not (fresh / parts[0]).exists():
            out.append((command, 2, "فایل پیدا نشد: " + parts[0]))
            continue
        code, text = run_py(*parts, cwd=fresh)
        out.append((command, code, text.strip().split("\n")[-1]))
    return out


BEFORE = run_readme(README_BROKEN)
print(f"{'دستورِ مستندشده':<34}{'نتیجه':>8}")
for command, code, _ in BEFORE:
    print(f"{command:<34}{('کار کرد' if code == 0 else 'شکست'):>8}")
print("کار کرد:", sum(1 for _, c, _ in BEFORE if c == 0), "از", len(BEFORE))
```

```text
دستورِ مستندشده                      نتیجه
python prepare.py                     شکست
python schema_check.py             کار کرد
python train.py --weeks 18            شکست
python evaluate.py                    شکست
python report.py --out out/report.md    شکست
python tools/lint.py                  شکست
کار کرد: 1 از 6
```

<div dir="rtl">

**یک از شش.**

و مهم‌ترین جزئیِ این آزمایش `fresh_checkout` است: کلِ `README` از اولین دستور تا آخرین، به ترتیب، در یک **نسخهٔ تازه** اجرا می‌شود. اگر همه را پشتِ سرِ هم در یک پوشهٔ کارکرده اجرا کنی، بعضی‌شان کار می‌کنند — چون فایلی که لازم دارند از دفعهٔ قبل مانده. **مستند برای کسی نوشته می‌شود که آن فایل‌ها را ندارد.**

## ۳. سه خانوادهٔ خرابی

</div>

```python
for command, code, last in BEFORE:
    if code:
        print(f"{command}\n    {last}")
```

```text
python prepare.py
    FileNotFoundError: [Errno 2] No such file or directory: 'raw/tickets.json'
python train.py --weeks 18
    train.py: error: the following arguments are required: --upto
python evaluate.py
    FileNotFoundError: [Errno 2] No such file or directory: 'models/model.json'
python report.py --out out/report.md
    FileNotFoundError: [Errno 2] No such file or directory: 'work/clean.json'
python tools/lint.py
    فایل پیدا نشد: tools/lint.py
```

<div dir="rtl">

**پنج شکست، ولی سه ریشهٔ متفاوت و دو قربانی — و درمانِ هر ریشه جای دیگری است:**

- **۱) مستندِ ناقص.** `prepare.py` به `raw/tickets.json` نیاز دارد و هیچ‌جا نگفته آن فایل از کجا می‌آید. نویسنده‌اش سه ماه پیش یک بار `fetch.py` را زده بود و یادش نمانده. **درمان: یک قدمِ گم‌شده به مستند اضافه شود.**
- **۲) مستندِ غلط.** گزینه زمانی `--weeks` بود و بعد `--upto` شد، و مسیرِ `lint.py` از `tools/` به `scripts/` رفت. کد جلو رفت و متن سرِ جایش ماند. **درمان: متن به‌روز شود.**
- **۳) کدی که مستند را غیرقابلِ اجرا کرده.** `report.py` می‌خواهد در `out/` بنویسد ولی خودش آن پوشه را نمی‌سازد. **درمان اینجا در متن نیست؛ در کد است** — چون هر راهنمایی‌ای که به کاربر بگوید «اول این پوشه را بساز»، فردا یک نفر فراموشش می‌کند. این خطا در جدولِ بالا هنوز دیده نمی‌شود: `report.py` پیش از رسیدن به نوشتن، روی نبودِ `work/clean.json` می‌افتد، و خطای `out/` تازه بعد از تعمیرِ `prepare.py` بیرون می‌آید.

**شکستِ `evaluate.py` هم چیزِ چهارمی است: آبشار.** خودش سالم است و فقط قربانیِ شکستِ مرحلهٔ قبل شده. خطایی که از `report.py` در جدول چاپ شد هم از همین جنس است. **در گزارش‌گیری، شکستِ آبشاری را از شکستِ واقعی جدا کن، وگرنه عددت را بزرگ‌تر از واقعیت نشان می‌دهی.**

</div>

```python
README_FIXED = as_readme([
    "python fetch.py",
    "python prepare.py",
    "python schema_check.py",
    "python train.py --upto 18",
    "python evaluate.py",
    "python report.py --out out/report.md",
    "python scripts/lint.py",
])
FILES["report.py"] = FILES["report.py"].replace(
    "args = parser.parse_args()\n",
    "args = parser.parse_args()\n"
    'import pathlib\npathlib.Path(args.out).parent.mkdir(parents=True, exist_ok=True)\n')
write(SOURCE / "report.py", FILES["report.py"])
write(SOURCE / "README.md", README_FIXED)
AFTER = run_readme(README_FIXED)
print(f"{'دستورِ مستندشده':<34}{'نتیجه':>8}   خروجی")
for command, code, last in AFTER:
    print(f"{command:<34}{('کار کرد' if code == 0 else 'شکست'):>8}   {last}")
print("کار کرد:", sum(1 for _, c, _ in AFTER if c == 0), "از", len(AFTER))
```

```text
دستورِ مستندشده                      نتیجه   خروجی
python fetch.py                    کار کرد   raw/tickets.json ساخته شد: 2400 ردیف
python prepare.py                  کار کرد   work/clean.json ساخته شد: 2400 ردیف
python schema_check.py             کار کرد   قرارداد سالم است: 2400 ردیف
python train.py --upto 18          کار کرد   models/model.json ساخته شد از 1800 ردیف
python evaluate.py                 کار کرد   دقت روی 600 ردیفِ آینده: 0.7933
python report.py --out out/report.md کار کرد   گزارش نوشته شد: out/report.md
python scripts/lint.py             کار کرد   همهٔ فایل‌ها docstring دارند
کار کرد: 7 از 7
```

<div dir="rtl">

**هفت از هفت** — و حالا ستونِ آخر یک چیزِ اضافه هم می‌دهد: **مستند دیگر فقط نمی‌گوید چه بزن، می‌گوید چه ببین.** «۲۴۰۰ ردیف»، «دقت ۰٫۷۹۳۳». کسی که فردا این را اجرا می‌کند، می‌داند نتیجه‌اش درست درآمده یا نه.

> ✅ **چک کن:** به تعدادِ دستورها نگاه کن، نه فقط به سهمِ موفق. از شش رفتیم به هفت، چون یک قدمِ گم‌شده اضافه شد. **اگر تستِ مستندت را طوری بنویسی که فقط سهم را گزارش کند، حذف کردنِ دستورهای دردسرساز آن را ۱۰۰٪ می‌کند.** عددِ درست همیشه دوتاست: چندتا از چندتا.

## ۴. حالا مستند هم یک دروازه دارد

مستندِ درست، فردا هم درست نمی‌ماند — مگر اینکه چیزی نگهش دارد. آن چیز همان دروازهٔ فصلِ قبل است.

بیایید کاری بکنیم که در هر پروژه‌ای هفته‌ای یک بار اتفاق می‌افتد: **نامِ یک گزینه در کد عوض شود.**

</div>

```python
def docs_gate(readme):
    """دروازهٔ مستند: چند دستورِ مستندشده در نسخهٔ تازه اجرا نمی‌شود."""
    broken = [c for c, code, _ in run_readme(readme) if code]
    return len(broken), broken


write(SOURCE / "train.py", FILES["train.py"].replace('"--upto"', '"--weeks"'))
n, broken = docs_gate(README_FIXED)
print("بعد از تغییرِ نامِ گزینه در کد — دستورِ شکسته:", n)
for command in broken:
    print("   ", command)
write(SOURCE / "train.py", FILES["train.py"])
print("بعد از برگرداندنِ کد — دستورِ شکسته:", docs_gate(README_FIXED)[0])
```

```text
بعد از تغییرِ نامِ گزینه در کد — دستورِ شکسته: 2
    python train.py --upto 18
    python evaluate.py
بعد از برگرداندنِ کد — دستورِ شکسته: 0
```

<div dir="rtl">

**کسی `README` را باز نکرد و بیلد قرمز شد.** این تفاوتِ «مستندی که کهنه نمی‌شود» با «مستندی که قول داده‌ایم به‌روزش نگه داریم» است: اولی یک سازوکار است، دومی یک نیت.

**و همان‌جا اولین قانونِ ثابتِ دوره برمی‌گردد: «اگر خودکار نیست، انجام نمی‌شود.»** به‌روز نگه داشتنِ مستندات دقیقاً همان کاری است که همه قبولش دارند و هیچ‌کس انجامش نمی‌دهد.

**این تست کند است** — هفت فرآیندِ جدا و یک کپیِ کاملِ پروژه — پس جایش ردهٔ کندِ فصلِ قبل است، نه دروازهٔ هر `push`.

## ۵. تصمیم‌نامه: نوشتنِ چیزی که diff نمی‌گوید

فصلِ ۱ نشان داد که بدنهٔ پیامِ commit جوابِ «چرا» را نگه می‌دارد. ولی بعضی «چرا»ها از یک commit بزرگ‌ترند: **تصمیم‌هایی که ماه‌ها روی کلِ پروژه اثر دارند.** جایشان یک فایلِ کوتاه است با پنج بندِ ثابت — و یک بندِ ششم که کمتر کسی می‌نویسد: **نگهبان**.

</div>

```python
DEPLOY = ('"""deploy.py — انتشارِ نسخهٔ تازه."""\n\n'
          'STAGES = ["canary", "full"]\n'
          'print("مرحله‌ها:", STAGES)\n')
write(SOURCE / "deploy.py", DEPLOY)
write(SOURCE / "split_check.py",
      '"""split_check.py — نگهبانِ تصمیمِ ۰۰۰۱."""\n'
      "import json\n\n"
      'rows = json.load(open("sample.json", encoding="utf-8"))\n'
      'train = [r["week"] for r in rows if r["week"] < 18]\n'
      'test = [r["week"] for r in rows if r["week"] >= 18]\n'
      'assert max(train) < min(test), "زمانِ آموزش و آزمون قاطی شده"\n'
      'print("تقسیم زمانی است:", max(train), "<", min(test))\n')
write(SOURCE / "release_check.py",
      '"""release_check.py — نگهبانِ تصمیمِ ۰۰۰۲."""\n'
      "import re\n\n"
      'text = open("deploy.py", encoding="utf-8").read()\n'
      'stages = re.search(r"STAGES = \\[(.+)\\]", text).group(1)\n'
      'assert "shadow" in stages, f"مرحلهٔ سایه در deploy.py نیست: {stages}"\n'
      'print("سایه پیش از قناری هست")\n')

ADR = {
    "0001-time-split.md": """# ۰۰۰۱ — تقسیمِ زمانی به‌جای تصادفی

وضعیت: پذیرفته‌شده
زمینه: با تقسیمِ تصادفی مدلِ الف ۰٫۵۹۳۸ می‌گرفت و مدلِ ب ۰٫۵۲۲۱.
تصمیم: ارزیابی فقط روی برشِ زمانیِ بعدی انجام می‌شود.
پیامد: رتبه‌بندی وارونه شد — الف ۰٫۲۲۷۱ و ب ۰٫۴۲۵۱ روی آینده.
بدیلِ ردشده: تقسیمِ تصادفی با چند seed. عددِ بهتری می‌داد و بی‌ربط بود.
نگهبان: python split_check.py
""",
    "0002-shadow-before-canary.md": """# ۰۰۰۲ — سایه پیش از قناری

وضعیت: پذیرفته‌شده
زمینه: قناریِ پنج‌درصدی با متریکِ تجمیعی در ۱۳ گروه از ۲۰ گروهِ ممکن مدلِ خراب را منتشر کرد.
تصمیم: هر انتشار اول مرحلهٔ سایه دارد، با متریکِ تفکیک‌شدهٔ زیرگروه.
پیامد: همان مدل در سایه با صفر کاربرِ آسیب‌دیده متوقف شد.
بدیلِ ردشده: بالا بردنِ سهمِ قناری. نمونه را بیشتر می‌کرد و آسیب را هم.
نگهبان: python release_check.py
""",
    "0003-keyword-model.md": """# ۰۰۰۳ — مدلِ شمارشیِ ساده

وضعیت: پذیرفته‌شده
زمینه: مدلِ سنگین‌تر روی این حجمِ داده جواب نمی‌داد.
تصمیم: فعلاً همان مدلِ شمارشی می‌ماند.
""",
}
FIELDS = ("وضعیت:", "زمینه:", "تصمیم:", "پیامد:", "بدیلِ ردشده:", "نگهبان:")
for name, text in ADR.items():
    write(SOURCE / "docs/adr" / name, text)


def audit_adr():
    """هر تصمیم‌نامه: بندهای لازم را دارد؟ نگهبانش همین حالا چه می‌گوید؟"""
    fresh = fresh_checkout()
    rows = []
    for name in sorted(ADR):
        text = (fresh / "docs/adr" / name).read_text(encoding="utf-8")
        missing = [f.rstrip(":") for f in FIELDS if f not in text]
        guard = re.search(r"نگهبان: (.+)", text)
        if not guard:
            state = "نگهبان ندارد"
        else:
            code, out = run_py(*shlex.split(guard.group(1))[1:], cwd=fresh)
            state = ("سبز" if code == 0 else "قرمز") + " — " + out.strip().split("\n")[-1]
        rows.append((name, missing, state))
    return rows


for name, missing, state in audit_adr():
    print(name)
    print("    بندِ گم‌شده:", "، ".join(missing) or "ندارد")
    print("    نگهبان:", state)
```

```text
0001-time-split.md
    بندِ گم‌شده: ندارد
    نگهبان: سبز — تقسیم زمانی است: 17 < 18
0002-shadow-before-canary.md
    بندِ گم‌شده: ندارد
    نگهبان: قرمز — AssertionError: مرحلهٔ سایه در deploy.py نیست: "canary", "full"
0003-keyword-model.md
    بندِ گم‌شده: پیامد، بدیلِ ردشده، نگهبان
    نگهبان: نگهبان ندارد
```

<div dir="rtl">

**سه تصمیم‌نامه، سه وضعیتِ کاملاً متفاوت — و اگر فقط می‌خواندیشان، هر سه یک‌جور به نظر می‌رسیدند.**

**۰۰۰۱ سبز است:** تصمیم نوشته شده و سامانه به آن عمل می‌کند.

**۰۰۰۲ قرمز است، و این بدترین حالتِ ممکن است.** یک تصمیمِ مکتوب، مستند، با زمینه و عدد و بدیلِ ردشده — و `deploy.py` مرحلهٔ سایه ندارد. **یعنی تیم فکر می‌کند این محافظت را دارد و ندارد.** بدونِ نگهبان، این وضع تا روزِ حادثه کشف نمی‌شد.

**۰۰۰۳ اصلاً تصمیم‌نامه نیست، یک یادداشت است.** «فعلاً همان می‌ماند» نه پیامدی دارد، نه بدیلی، نه نگهبانی. **جملهٔ «مدلِ سنگین‌تر جواب نمی‌داد» هیچ عددی ندارد** — پس شش ماهِ دیگر هیچ‌کس نمی‌تواند بگوید هنوز درست است یا نه.

## ۶. تصمیم را واقعی کن

</div>

```python
write(SOURCE / "deploy.py", DEPLOY.replace('["canary"', '["shadow", "canary"'))
for name, missing, state in audit_adr():
    print(name, "→", state)
```

```text
0001-time-split.md → سبز — تقسیم زمانی است: 17 < 18
0002-shadow-before-canary.md → سبز — سایه پیش از قناری هست
0003-keyword-model.md → نگهبان ندارد
```

<div dir="rtl">

یک کلمه در `deploy.py` اضافه شد و تصمیم از «نوشته‌شده» به «برقرار» رفت. **این تفاوتِ مستندسازی و اجراست، و نگهبان تنها چیزی است که آن‌ها را از هم جدا نگه می‌دارد.**

> 📏 **اندازه بگیر:** **با چه چیزی مقایسه شد؟** با خودِ همان مستند، پیش و پس از تعمیر: ۱ از ۶ به ۷ از ۷. **روی کدام داده؟** روی یک **نسخهٔ تازهٔ** پروژه در هر اجرا — که تنها شرطِ معنادار بودنِ این آزمایش است. **با چند `seed`؟** اینجا تصادفی در کار نیست و همین را باید صریح گفت: **این اندازه‌گیری قطعی است، و اگر روی ماشینِ تو عددِ دیگری داد، یعنی محیطت با نسخهٔ تازه فرق دارد** — که خودش یافتهٔ مهمی است، نه نوسان.

> 🔧 **اگر کار نکرد:** اگر تستِ مستند روی سیستمِ تو همه را «کار کرد» نشان داد، اولین چیزی که باید ببینی `fresh_checkout` است — احتمالاً پوشهٔ قبلی پاک نشده و فایل‌های مرحله‌های قبل مانده‌اند. اگر `shutil.copytree` با `FileExistsError: [WinError 183]` ایستاد، همان یک ردیفِ `rmtree` بالایش اجرا نشده. و اگر `re.search` روی بندِ «نگهبان» `AttributeError: 'NoneType' object has no attribute 'group'` داد، تصمیم‌نامه‌ای آن بند را ندارد — که خودش جوابِ سؤال است، پس در کد به‌جای `try` یک شرطِ صریح گذاشته‌ایم.

> 🤖 **از دستیارت بپرس:** «تصمیم‌نامه (ADR) چیست و چه بندهایی دارد؟» بعد این را بپرس: **«برای هر بندی که گفتی، یک راهِ خودکار پیشنهاد بده که نقضش را بگیرد.»** — بندهایی که جوابِ خوبی نمی‌گیرند، همان‌هایی‌اند که در عمل هم کسی رعایتشان نمی‌کند.

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| executable documentation | اگزکیوتبل داکیومنتیشن | مستندی که دستورهایش واقعاً اجرا و آزموده می‌شوند |
| fresh checkout | فرش چک‌اوت | نسخهٔ تازهٔ پروژه، بدونِ هیچ فایلِ به‌جامانده از کارهای قبلی |
| ADR | ای‌دی‌آر | تصمیم‌نامه: یک فایلِ کوتاه که زمینه، تصمیم، پیامد و بدیل‌ها را نگه می‌دارد |
| doctest | داک‌تست | اجرای نمونه‌های داخلِ مستند به‌عنوان تست |
| stale docs | استیل داکس | مستندی که کد از آن جلو زده و کسی خبر ندارد |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا اجرای دستورها در یک پوشهٔ کارکرده، نتیجهٔ این آزمایش را بی‌معنا می‌کند؟

**تمرینِ اجباری:** `README` پروژهٔ خودت را بردار و همین تست را رویش ببند. **سه عدد گزارش کن:** چند دستور مستند شده، چندتا در نسخهٔ تازه اجرا می‌شود، و چندتا از شکست‌ها **آبشاری** بودند نه واقعی. بعد هر شکست را در یکی از سه خانوادهٔ بخشِ ۳ بگذار. **و جوابِ اصلی را بنویس: خانوادهٔ غالبِ خرابیِ تو کدام است؟** جوابت می‌گوید مشکلِ تیمت نوشتن است یا به‌روز نگه داشتن.

**تمرینِ ستاره‌دار ⭐:** سه تصمیمِ واقعیِ پروژه‌ات را به‌شکلِ تصمیم‌نامه بنویس و برای هر کدام یک **نگهبانِ اجراشدنی** بساز. بعد هر سه نگهبان را اجرا کن. **و سؤالِ سخت را جواب بده: اگر یکی از نگهبان‌ها قرمز درآمد، تصمیم را عوض می‌کنی یا سامانه را؟** جوابت را همان‌جا در بندِ «وضعیت» بنویس — چون یک تصمیمِ عوض‌شده که هیچ‌جا ثبت نشود، دقیقاً همان چیزی است که این فصل دربارهٔ آن است.

## در فصل بعد

تا اینجا از **آنچه می‌دانیم** محافظت کردیم: کد، داده، مستند. **فصلِ بعد سراغِ آن چیزی می‌رود که هنوز اتفاق نیفتاده.**

یک سیاههٔ ریسک می‌سازیم که ردیف‌هایش شکست‌های **واقعیِ** پنج ترمِ قبل‌اند، هر کدام با احتمال و اثر و این سؤال که «آیا چیزی خودکار می‌گیردش؟». و بعد یک ردِ ممیزی می‌سازیم: **یک شمارهٔ پیش‌بینی می‌دهی و کد بازسازی می‌کند که کدام نسخهٔ داده، کدام نسخهٔ کد و کدام نسخهٔ مدل آن جواب را ساخته.**

</div>

---
Source: https://yaadestan.com/courses/darbast/lessons/t6/s03-docs-that-survive (یادستان, Yaadestan)
