Lesson 13 / الدرس 13
Most of the job is writing / معظم العمل كتابة
Commit messages, pull requests, chat, documentation, the note explaining why. You will write far more prose than code, and it will be read by people who are busy, in a hurry, and often not reading in their first language.
رسائل الإيداع، وطلبات السحب، والدردشة، والتوثيق، والملاحظة التي تفسّر لماذا. ستكتب نثرًا أكثر بكثير من الكود، وسيقرؤه مشغولون مستعجلون، وكثيرًا لا يقرؤون بلغتهم الأولى.
Nobody reads work writing the way they read a book. They skim for the part that concerns them, and if they cannot find it in a few seconds they close it and it may as well not exist. That is not laziness — it is what happens to anyone with forty messages and a deadline, and writing for it is a skill rather than a compromise.
Four things that make writing get read
| Do | Because |
|---|---|
| Put the conclusion first | The reader can stop after one line and still have what they needed |
| Say who has to do something, by name | "Someone should look at this" is read by everybody and acted on by nobody |
| One idea per paragraph, short paragraphs | A wall of text is skipped whole; four short ones get scanned and one gets read |
| Say what you want back | Approval, an opinion, or nothing — a reader who does not know what you want gives you nothing |
The second row is the single most useful habit here. Diffusion of responsibility is real and completely predictable — a message addressed to a channel is addressed to no one, and adding one name at the front changes the outcome more than any amount of rewriting the middle.
Writing for people who are translating as they read
-
Short sentences, and one clause each where you can. A long sentence with three subordinate clauses is hard in your own language and much harder in a second one. جمل قصيرة، وشرطٌ واحد لكلٍّ ما استطعت. فالجملة الطويلة بثلاث جمل تابعة عسيرة بلغتك وأعسر بكثير بلغة ثانية.
-
Avoid idioms and sport. "Ballpark", "touch base", "out of left field" — these carry nothing to somebody who has not lived where they came from, and there is always a plain word. وتجنّب الاصطلاحات والرياضة. فعبارات كهذه لا تحمل شيئًا لمن لم يعش حيث نشأت، وثمة كلمة صريحة دائمًا.
-
Spell out the abbreviation the first time. Your team's three letters are not universal, and somebody who joined last week is guessing rather than asking. واكتب الاختصار كاملًا أول مرة. فحروف فريقك الثلاثة ليست عالمية، ومن انضم الأسبوع الماضي يخمّن لا يسأل.
Check yourself / اختبر نفسك
1. Why put the conclusion first?
If they cannot find it in a few seconds they close it, and it may as well not exist. That is not laziness, it is forty messages and a deadline.
2. What happens to "someone should look at this"?
Diffusion of responsibility is real and completely predictable. A message addressed to a channel is addressed to no one.
3. Why write a decision into the commit or the code rather than only the chat thread?
One line where the thing lives outlives every chat tool the company will use — the same argument the handover lesson made about the runbook.
Score / النتيجة: 0 / 3