Lesson 16 / الدرس 16
Writing down what only you know / كتابة ما لا يعرفه سواك
Every running system has facts that exist in one person's head — where it lives, how to deploy it, what breaks at month end. Writing them down is the last piece of taking something live, and the piece that decides whether it survives you.
كل نظام عامل فيه حقائق تعيش في رأس شخص واحد — أين يعيش، وكيف يُنشر، وما ينكسر آخر الشهر. وكتابتها آخر قطعة في إطلاق شيء، والقطعة التي تقرر أينجو بعدك.
The test is simple and uncomfortable: if you were unreachable for two weeks, could someone else deploy a fix? For most small systems the answer is no, and not because the work is hard — because five facts are undocumented and each one is a dead end for whoever is trying.
One page, and it lives in the repository
| Question | What the answer must contain |
|---|---|
| Where does it run? | Host, account, PHP version, where the document root is |
| How do I deploy? | The exact command, and how to tell whether it worked |
| How do I roll back? | The exact command. Untested rollbacks are not answers |
| Where are the logs? | Full paths, and what each one is for |
| Who holds the credentials? | Not the credentials — where they are and who can grant access |
| What runs on a schedule? | Every cron entry, what it does, and what happens if it stops |
| What breaks predictably? | The known quirks. This is the section only you can write |
The last row is the one that has value nobody else can provide. "The nightly import fails if the file is late; rerun it with this command" is knowledge that exists in exactly one place, and it is the difference between a colleague solving something in a minute and losing a morning to it.
Keep it in the repository, next to the code, in a file called something obvious. Documentation in a wiki, a chat pin or a shared drive drifts away from the thing it describes — a change to the deploy script and a change to the sentence describing it should be the same commit, reviewed together, or the second one will not happen.
Comments that earn their place
<?php
// Bad: says what the line says.
// Loop through the courses
foreach ($courses as $course) {
// Good: says what could not be recovered by reading.
//
// Physical padding-left, not padding-inline-start. This element is
// inside dir="rtl", where the logical property flips and puts the
// rule on the wrong side. Verified in Chrome; changing it back
// breaks the Arabic layout in a way no test catches.
// Good: says why the obvious thing is wrong.
//
// --delete is safe INSIDE these because each directory is wholly
// owned by the repo. One level up it would remove mail/ and ssl/,
// which are not in git and are not recoverable.Check yourself / اختبر نفسك
1. What is the test of whether a system is documented?
For most small systems the answer is no, and not because the work is hard — because a handful of facts are undocumented and each is a dead end.
2. Why keep the runbook in the repository rather than a wiki?
Documentation away from the code drifts from it. Keeping them together makes updating the description part of making the change rather than a separate task nobody does.
3. What makes a code comment worth writing?
A reader can see what a loop does. They cannot see that the logical CSS property was tried first and flipped the layout inside dir="rtl".
Score / النتيجة: 0 / 3