教學文章的標題是這一篇的主旨:講的對象是什麼、交付哪一種內容。段標是這一節的主旨。標題與段標不寫成結論句——「X 決定 Y」「X 不是 Y,是 Z」「X 才是 Y」這類斷言留在正文裡推導走完的位置,那裡的讀者已經有在乎它的理由。

結論句進標題的缺陷本卡稱為「帶前提的結論」:讀者在乎那句結論的理由是由本篇正文建立的,而標題是讀者還沒讀正文時看到的那一行。

本卡來自一次標題審查。一篇 HTTP 轉址文章的暫定標題是「轉址回應的語意與撤回性:狀態碼管解讀,快取標頭管收不收得回來」,站主讀到的反應是「為什麼我要在乎能不能收回來」。

失效的形態

標題的後半句是推導最下游的後果

「快取標頭管收不收得回來」這一句成立,需要讀者先知道三件事:瀏覽器與中間的快取會保存轉址回應、保存多久由回應裡的標頭指定、保存期間瀏覽器不再向伺服器詢問。知道這三件事之後,「改了目的地而舊的轉址收不回來」才是一個問題。標題把這個問題的答案寫出來,而問題本身要到正文中段才出現。

同一批的另外幾個標題與一個段標是同一個形態:

標題讀者要先從正文拿到的前提
短網址的商業模型:客戶不為轉址本身付錢,誰出錢維持轉址決定連結能活多久轉址要有人持續付錢才維持得住;連結會隨出資者停止而失效
短網址服務的需求定義:商業模型與使用情境決定轉址、保存與濫用的規格這些規格有不只一種定法;各種定法之間的差別來自商業模型
短網址服務的實作:轉址路徑的可用性與可撤回性主導快取與點擊紀錄的取捨「可撤回性」指什麼;快取與點擊紀錄為什麼互相牽制
(段標)快取標頭決定瀏覽器還會不會回來,也就決定瀏覽器這一層的撤回延遲「撤回延遲」指什麼;瀏覽器「不回來」是指不再向伺服器發出請求

標題被別篇拿去當連結文字時,前提離得更遠

連結文字寫完整標題是本站的規則,理由是只寫編號的連結讀者要點進去才知道講什麼。這條規則把標題搬到另一篇文章的句子裡,而那一篇的讀者連本篇的主題都還不知道。標題是主旨時,他讀到的是「那一篇講短網址服務怎麼實作」;標題是帶前提的結論時,他讀到的是一句關於「可撤回性」的斷言,而他不知道那個詞指什麼、也不知道為什麼要在乎。

口語動詞讓後半句連結論都沒交付

「狀態碼管解讀,快取標頭管收不收得回來」的動詞是「管」。它沒有說狀態碼對解讀做了什麼、快取標頭對回應做了什麼。這一項由句子層的槽位規則處理(動詞要是領域裡的操作),與前提的問題獨立:把「管」換成「決定」之後,前提的問題原樣還在。

讀得懂的結論句也改寫成主旨

同一個分類裡有一個寫成結論的標題讀者讀得懂:「ON 描述關係、WHERE 篩選結果」。它的四個名詞——ON、WHERE、關係、篩選——讀者進到 SQL 這個分類之前就有。所以缺陷的成因是前提在哪裡:前提在讀者到達之前的知識裡,結論句讀得懂;前提在本篇正文裡,結論句把讀者還沒有的東西當成他已經有的。

規則仍然定成一律寫主旨,理由有兩個。

寫標題的人分不出這兩種結論。 他已經讀完全文,每一個前提都在他手上,問他「這個前提讀者進來之前有沒有」,他用的是讀完之後的知識在答。一條要靠這個判斷才能執行的規則,在最需要它的時候會放行。「標題裡有沒有謂語在下斷言」則是寫的人看得出來的。

讀得懂的結論句沒有多交付主旨沒交付的東西。 「ON 與 WHERE:連接條件與篩選條件各自的職責」說出了同樣的對象與同樣的內容種類,而結論在正文第一節就會出現。

檢查方法:把標題當成別篇裡的一個連結文字讀一次

檢查的位置固定在讀者條件最差的那一個:他在另一篇文章裡讀到這個標題,沒讀過本篇。逐項問:

  1. 謂語:標題有沒有對某件事下斷言(決定、主導、取決於、不是、才是、等於、只是,或任何「主詞+動詞+受詞」的完整句)。有就改寫成主旨。
  2. 名詞:標題裡每一個名詞,這位讀者知不知道它指什麼。本篇正文才定義的詞(可撤回性、撤回延遲)換成他認得的詞。
  3. 主旨:只憑這一行,讀者說不說得出這一篇講的對象是什麼、讀完會得到哪一種內容(一套機制的說明、幾種做法的取捨、一種判讀方法、一段流程)。

「主旨」那一題不通過而另外兩題通過的標題與段標,是過短的標籤(「成本模型」「判讀方式」)或帶指示詞的名詞子句(「為什麼只收這幾本」),處置見〈沒有下斷言的標籤式段標同樣要改〉;標籤被多處引用時展開成本怎麼累積,見壓縮標籤的成本乘以引用點數。

段標用同一組問句,而讀者手上多了本篇前文:前文已經定義過的名詞可以用,謂語那一題不放寬。

「對象+動詞」而不下斷言的寫法是主旨,不在謂語那一題的範圍內:「從入口程式看應用啟動流程」「用完整分析框架重新評估一間連鎖早餐店」描述的是這一篇做的事。

沒有下斷言的標籤式段標同樣要改

第一輪改名留下一批沒有下斷言、因此通過「謂語」那一題的段標:「往下讀」「判讀方式」「接到哪裡」「為什麼只收這幾本」「這個主題接到哪裡」「怎麼判斷自己在哪個位置」。它們在「主旨」那一題不通過——把段標單獨拿出來,不讀內文的人不知道判讀的是什麼、往下讀到哪些主題、「這幾本」是哪幾本。

處置有兩個,沒有第三個:

  • 換成寫出對象的主旨:指示詞(這幾本、這個主題、這個位置)與泛用的標籤換成它指的東西。同一個標籤在一個分類的二十幾篇重複出現時,每一篇各自寫出自己的對象。
  • 寫不出有意義的主旨就移除段標,那一節併進相鄰的節。段標存在的理由是讓讀者不讀內文就知道這一節講什麼;做不到這件事的段標只是一道分隔線。

全站慣用的固定收尾段名(「下一步路由」「判讀訊號」「往下走」「往下讀」)不是例外:它們是規範裡的概念名被直接拿來當段名,而每一篇那一節連到的主題各不相同。寫成「內容種類:那一節實際連到或判讀的對象」,例如「延伸閱讀:對手方、槓桿的強制平倉與機會成本」。

過短的標籤式標題(「對人負責」「契約條款的送達」)比照處理:冒號之後補上涵蓋的成員。標題為了寫出成員而變長是可以接受的,被別篇當成連結文字時讀者拿到的資訊也跟著變多。

標題的寫法

  1. 先寫主旨句:這一篇講什麼對象的什麼。對象用領域裡通用的名字,內容種類寫出來(機制、選型、取捨、流程、判讀)。
  2. 冒號之後寫這一篇涵蓋的成員,用讀者認得的詞。成員寫得出來時不寫計數。
  3. 想寫進標題的那句結論放回正文裡推導走完的位置。確認正文那個位置真的有這一句;標題原本是它唯一的住址時,改標題等於刪掉結論。
  4. 改完之後核對 description:教材的 description 交代涵蓋範圍,標題改成主旨之後兩者可能重疊;遮住 description 只看標題猜得出全部內容時,重寫 description 去補標題說不完的範圍。

套到上面那一批(示意,定稿以各篇內容為準):

改前改後
轉址回應的語意與撤回性:狀態碼管解讀,快取標頭管收不收得回來HTTP 轉址回應:狀態碼的語意與快取標頭指定的保存行為
短網址的商業模型:客戶不為轉址本身付錢,誰出錢維持轉址決定連結能活多久短網址的商業模型:訂閱、自架、平台內建與廣告插頁各由誰出資維持轉址
短網址服務的需求定義:商業模型與使用情境決定轉址、保存與濫用的規格短網址服務的需求定義:自建或購買、保存期限、目的地修改與濫用處理的規格
短網址服務的實作:轉址路徑的可用性與可撤回性主導快取與點擊紀錄的取捨短網址服務的實作:短碼生成、對照表儲存、轉址快取與點擊紀錄
(段標)快取標頭決定瀏覽器還會不會回來,也就決定瀏覽器這一層的撤回延遲(段標)轉址回應的快取標頭與瀏覽器保存回應的時間

改後的每一行都沒有交付結論,而結論沒有消失:「誰出錢維持轉址,連結的壽命就跟著誰」仍然是那一篇正文推導出來的東西,位置在出資方式逐一講完之後。

成因:規範要求標題承載結論

本站的寫作規範先前寫著「標題與段標是承載結論的直述句」。這一句是為了擋掉問句標題與懸念段標而立的(見寫給帶問題來的讀者),它要求的是直述,而條文把直述寫成了結論。

生成端照條文寫,而一篇文章裡最像「結論」的句子是推導最下游的那一句——它最有資訊量、最不像目錄。於是標題固定取到前提最多的那一句。

這個歸因有量測支持。以該條文寫進規範的日期切開教學文章(排除檢討卡、工作紀錄、知識卡、目錄頁與案例),用一組謂語關鍵詞找候選:

量的東西條文之前建立的文章條文之後建立的文章
標題命中謂語關鍵詞1304 篇中 70 篇106 篇中 26 篇
段標命中謂語關鍵詞15939 個中 570 個591 個中 98 個
段標含逗號(兩個子句以上)15939 個中 224 個591 個中 127 個

候選率在標題上是百分之五對百分之二十五,在含逗號的段標上是百分之一對百分之二十一。另從全部教學標題隨機抽一百篇逐條判讀,結論句或問句形式的標題約十三篇,其餘是主旨式標題。存量的多數因此不需要改,需要改的集中在條文生效之後寫的與重寫過的分類。

多輪審查不產生 finding 的原因

寫標題的人與審標題的人都讀過全文,前提在他們手上,「可撤回性主導快取的取捨」對他們是一句完整而準確的摘要。這與審查者手上有作者的地圖是同一個成因,差別在位置:那張卡的指稱隔了好幾段,這裡的前提隔了一整篇正文,而且讀者是從另一篇文章讀到它的。

規範這一側則是合規的:標題是直述句、承載結論、沒有問號。對照規範找違規的審查在這個位置沒有東西可報。

偵測

關鍵詞只用來縮小要讀的範圍:

1# 標題裡的謂語候選;「管理」「決策」這類名詞會混進來,命中後逐條判讀
2rg -n '^title:.*(決定|主導|取決|不是|而是|才|就是|等於|只是|只有|由誰)' content/
3# 兩個子句以上的段標
4rg -n '^#{2,3} .*[,,]' content/

「謂語」那一題寫的人自己判得出來。「名詞」與「主旨」兩題他判不準,因為他答的時候用的是讀完全文之後的知識。這兩題可靠的做法是把一批標題單獨交給沒讀過正文的讀者(低階模型的讀者探針合用),只給標題清單,問每一條:這一篇會講什麼、哪個詞不知道指什麼、標題說的那件事為什麼重要。答不出「為什麼重要」而文章確實是在講那件事,就是前提在正文裡;這也是存量裡結論式標題的偵測方式。

論述基礎與限制

  • 問題由一位讀者指出,成因分析是從他的三句意見與四個實例推出來的;「一律寫主旨」這條線由他裁定。檢查方法沒有經過讀者探針的驗證,本卡寫成時那一步還沒跑。
  • 關鍵詞候選不是判定。上表的兩個比例量的是寫法的形態改變,不是違規率;一百篇的逐條判讀由寫這張卡的同一個來源做,同源判讀對這一類有前述的結構上限,十三這個數字可能偏低。
  • 日期取 frontmatter 的 date,重寫過而沿用舊日期的文章算在條文之前,所以「之前」那一欄混進了一部分條文之後的寫法,兩欄的實際差距比表上大。
  • 適用範圍是教學文章。檢討卡與工作紀錄的讀者帶著一個已經遇到的問題來,標題寫成結論時前提多半就是他手上那個問題;這兩類要不要比照,本卡沒有材料判斷。

跟其他抽象層原則的關係

  • 寫給帶問題來的讀者:本卡推翻它的一條結論。那張卡規定標題承載結論,理由是標題是掃列表的讀者唯一保證讀到的一行;本卡指出那一行要交付的是主旨,結論進標題時讀者還沒有在乎它的理由。那張卡擋問句標題與懸念段標的部分不受影響,結論的位置仍然是正文裡推導走完的地方。
  • 規範指定了某個位置要交付什麼,全批長成同一個模板:同一條路徑的又一個位置。那張卡記的是「每段首句先說核心原則」在文章第一段生效,全批首句都是結論句;本卡是「標題承載結論」在標題生效,生成端替「結論」選了同一種句子。
  • 把 description 寫成觸發條件:同族。那張卡的 description 預設讀者帶著一個問題,本卡的標題預設讀者帶著一個前提;兩者都把讀者還沒有的東西寫進了他最先讀到的位置。
  • 名詞要求的「誰的、什麼的」也是槽位:檢查方法的「名詞」那一題是它在標題上的形態——標題裡的名詞所屬與所指,要能從標題這一行解出來,因為被當成連結文字時沒有前一句可以依靠。
  • 標題涵蓋不了內容時,該問的是這篇裝了幾個概念:相鄰的另一個標題問題。那張卡處理標題比內容窄,本卡處理標題比讀者手上的知識遠;一個帶前提的結論通常同時也比內容窄,因為它只取了推導的最後一句。

判讀徵兆

徵兆該做的行動
讀標題的人問「為什麼我要在乎這個」標題是帶前提的結論;改寫成主旨,結論放回正文
標題裡有一個本篇正文才定義的詞換成讀者認得的詞,或把那個詞留給正文
標題冒號之後是一句「X 決定 Y」,而 Y 是本篇後半才談到的東西冒號之後改寫成這一篇涵蓋的成員
別篇引用這個標題當連結文字,那一句讀起來像沒頭沒尾的斷言以那一句的讀者為準跑檢查方法
段標有兩個子句、第二個子句以「也就」「所以」「而」接上一個後果後果是這一節的結論,留在節內;段標寫這一節講的對象
標題改成主旨之後與 description 幾乎相同重寫 description,補標題說不完的範圍