英語技術文檔的標題到底該大寫還是小寫？

Foreword

在寫英語技術文檔的過程中，Technical Writer 必定會遇到的一個問題就是：標題到底該大寫還是小寫？

為了便於理解，將這個問題拆分一下：

1. 標題：這裡指的是一篇文檔的一級標題和正文里的各級標題，一級標題可以理解為 page title 或 page heading。
2. 大寫還是小寫：指的是英語技術寫作中的兩種大小寫規範，即 headline-style 和 sentence-style。那這兩種規範又分別是什麼意思呢，且往下看。

如果是一個比較成熟的產品，那可以選擇沿用現有規範。如果是一個比較新的產品，文檔尚未形成固定規範，那就需要做出一個選擇，制定一個規範，而且一旦制定就要嚴格遵循，確保一致性。

可以說，規範文檔的大小寫是從 style 的一個小方面出發來提高文檔質量。雖說大小寫是一個小方面，但它特別直觀，能快速地給文檔用戶留下第一印象。

在筆者看來，採用哪一種大小寫規範不是最重要的，關鍵是要統一使用一種規範，並嚴格執行下去。就像一個與你穿衣風格迥然不同的人，如果做到極致的講究和精緻，你很可能並不會覺得 TA 是錯的，反而會欣賞，因為那也是一種風格，那就是 TA 的風格。

正文結構：

• 大小寫規範具體指什麼？
• 為什麼要確定大小寫規範？
• 知名 Style Guide 中的大小寫規範
• 實際英語技術文檔中的大小寫應用現狀
• 如何為技術文檔選擇大小寫規範？

溫馨提醒：點擊文中配圖可放大查看清晰大圖。

大小寫規範具體指什麼？

技術寫作中的大小寫規範主要包括兩種，即：headline-style capitalization 和 sentence-style capitalization。

• Headline-style capitalization：即對所有重要單詞都採用首字母大寫。例如：TiDB Quick Start Guide
• Sentence-style capitalization：即只對第一個單詞採用首字母大寫，專有名詞、商標名、產品名、公司名等必須大寫的詞語也採用大寫。例如：Scale the TiDB cluster，Development and testing environments

從頁面呈現和視覺感知來講，兩種大小寫規範存在明顯差異。

為什麼要確定大小寫規範？

1. 保持文檔風格的一致性，提高文檔的整體質量。

對於英語技術文檔來說，統一的大小寫規範可有效提高文檔的整體質量。

一個產品的技術文檔是一個整體，既然是一個整體，就要有這個整體所共同遵循的一些規則，而大小寫就是其中重要的一項。常見的 Style Guide 都有專門的 Capitalization 這一項。

在實際工作中，我發現其實中文技術文檔中也常常存在大小寫問題，只不過不局限於標題。

例如，一些產品名等特殊名詞，一旦確定了就應在所有文檔中保持絕對一致，而這一點是技術人員容易忽略的。對於文檔用戶，卻留下了潛在的困惑：咦，這前後說的到底是不是一個東西？這就需要在 Review 這一環節格外注意。

2. 提升產品在用戶心目中的形象。

一個好產品可以給用戶留下一個好印象，一個好的文檔可以給用戶留下嚴謹、細緻、規範、可靠的印象，進而提升產品印象在用戶心目中的形象。

相反，如果標題大小寫使用混亂，幾個大寫的交叉著一兩個小寫的，試想用戶會產生什麼想法或者困惑呢？

如果是我，我可能會想：那些大寫的標題是否有特殊含義？為什麼有的大寫有的小寫？這個產品的文檔質量不怎麼樣啊，有點兒亂……雖然我不是處女座，但看起來好難受，簡直不能忍……

一言以蔽之，確定並遵循大小寫規範有利於保證文檔風格的一致性，提高文檔質量，提升產品形象。

知名 Style Guide 中的大小寫規範

現在已經清楚了什麼是大小寫規範，以及確定大小寫規範的必要性。

那麼，業內熟知的一些 Style Guide 對大小寫規範是如何限定的呢？接下來分享一下 IBM Style Guide 和 Google Style Guide 中對大小寫規範的描述。

IBM Style Guide

這裡所說的 IBM Style Guide 指的是下面這本書：

在 The IBM Style Guide 中，大小寫規範放在了 Chapter 1 Language and grammar 下。具體見下圖：

其中，關於 Capitalization 的使用概括如下：

In general, use a lowercase style in text and use sentence-style capitalization for headings.

具體到 Capitalization in headings and titles 部分：

Use sentence-style capitalization for these items:

- Headings in books (except the book title)

- Topic titles and headings in information centers

- Titles and headings in online information, such as tutorials, samples, developerWorks? articles, technotes, and websites

- Titles of white papers and marketing content

那 title 就沒有用大寫的時候嗎？有的，往下看：

- Titles of books

- Titles of CDs

- Titles of stand-alone information units, such as information centers, quick start guides, and courses

除了標題外，大小寫在其它場景的使用也有其規範，這些場景已在上面的圖裡列出，感興趣的小夥伴可以去看看。

Google Style Guide

這裡所說的 Google Style Guide 指的是 Google Developer Documentation Style Guide。

鏈接：https://developers.google.cn/style/

與 The IBM Style Guide 類似，Google Style Guide 也將 Capitalization 放在了 Language and grammar 目錄下。

其中，關於 Capitalization in titles and headings 部分的規範描述如下：

In document titles and page headings, use sentence case. That is, capitalize only the first word.

Exception: for proper nouns, trademarks, keywords, and other terms that are always capitalized a certain way, use the standard capitalization for the term, regardless of where it appears in the title or heading.

Even though youre using sentence case, dont put a period at the end of a heading.

小結：綜上來看，無論是 IBM Style Guide，還是 Google Style Guide，都對標題採用的 sentence-style capitalization，即只對標題中的第一個單詞採用首字母大寫。

實際英語技術文檔中的大小寫應用現狀

註：此部分配圖均截圖自產品的官方文檔，截圖日期為 2018 年 1 月 14 日。不排除該日期後會有更新完善，特此說明。

據筆者觀察，即便是國內外大公司，也很難做到標題大小寫風格的完全統一。

如果是一個人寫文檔，保持一種風格相對容易；如果是很多人協作，涉及流程管理，那就難免會有疏漏。

先來看下上面提到的 IBM 和 Google 的文檔，兩者均在 Style Guide 中寫明對標題使用 sentence-style，這也是筆者常見到的技術文檔標題規範。但是，在實際的技術文檔中，反倒是 headline-style 較為多見。

那麼，具體一點，當前實際的產品文檔是如何處理標題大小寫的呢？

別急，馬上就給你舉栗子啦！

IBM DB2 文檔標題的大小寫

以 IBM 的 DB2 為例，其文檔總體採用的 sentence-style。

IBM DB2 文檔鏈接：https://www.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.welcome.doc/doc/welcome.html

但是，也存在大小寫不一致的情況，如下所示：

這裡的 "Updates" 不應該使用首字母大寫。

另外，多說一句，還順便發現了其它一些問題，如下所示：

依筆者之見，不論是哪家公司的文檔，只要你帶著一雙敏銳的眼睛去看，總能發現一些問題，而且很容易發現。

Google Cloud Spanner 文檔標題的大小寫

以 Google 的 Cloud Spanner 為例，其文檔採用的大小寫規範是：頁面標題（一級標題）採用的是 headline-style，文內標題採用的則是 sentence-style。

Google Cloud Spanner 文檔鏈接：https://cloud.google.com/spanner/docs/

第一次看到時的反應是：納尼，還可以玩混搭？

別說，似乎效果還不錯，因為這樣頁面標題和文內標題的區分更明顯了。在總目錄里顯示的是 headline-style 的大標題，點擊一個標題進去，右側顯示的是 sentence-style 的本文目錄。

上圖地址：https://cloud.google.com/spanner/docs/create-manage-instances

整體來看，Google Cloud Spanner 文檔的大小寫使用還是比較統一的，筆者感覺比 IBM DB2 的更易用，無論是文檔架構還是頁面設計。

雖說瑕不掩瑜，但是呢，也存在一些小瑕疵，比如：

這裡一個 "using" 忘記採用首字母大寫了……

如此看來，Google Cloud Spanner 文檔也並沒有做到嚴格遵循 Google Style Guide。

DB-Engines Ranking 排名前十的資料庫文檔

鑒於筆者當前工作是資料庫產品的 Technical Writer，於是參考 2018 年 1 月份的 DB-Engines Ranking 排名，對資料庫產品的文檔進行了一個關於大小寫規範的小調查。

那麼問題來了，DB-Engines Ranking 是個什麼鬼？

鏈接：https://db-engines.com/en/ranking

The DB-Engines Ranking ranks database management systems according to their popularity. The ranking is updated monthly.

大小寫規範的調查結果如下表所示：

註：上表統計為某個產品文檔總體的大小寫風格，如果在 Headline-style 中夾雜著個別 sentence-style 或者疏漏導致的大小寫不一致，不計入此表。

上表中均已附上鏈接，為了讓大家快速直觀地理解，下面上幾個比較有代表性的圖：

如何為技術文檔選擇大小寫規範？

看到這裡，你已經對英語技術文檔中的大小寫規範有了一個較為全面的了解。

當前情況是在 Style Guide 中的文字規定中，往往是 sentence-style，但在實際的應用中卻是 headline-style 居多。即便是明確制定規範者，也並沒有完全依照規範執行。

那麼，如果你要給一個新產品寫英語技術文檔，該如何選擇大小寫規範呢？這裡筆者給初入技術寫作的小夥伴提供一種解決思路：

1. What：搞清楚技術文檔中的大小寫規範指的是什麼。
2. Why：為什麼要確定大小寫規範。
3. 站在前人的肩膀上：了解那些全球知名大公司是如何規定大小寫規範的。
4. 行業現狀：了解產品所屬領域的佼佼者們的文檔大小寫現狀。
5. 發揮主觀能動性：理論規範+實際現狀+主觀決定。

對於英語技術文檔標題的兩種大小寫規範，很難說哪一種是對的，哪一種是錯的，可以說並無對錯之分。

Afterword

無規矩不成方圓，有規矩不遵循同樣不成方圓。

採用哪一種大小寫規範不是最重要的，審慎地選擇和確定一種大小寫規範，然後嚴格執行和遵守才是最重要的。

如果你好奇筆者當前做的文檔採用的是哪種規範，可以戳：PingCAP Documentation。

是的，採用的是類似 Google Cloud Spanner 文檔的大小寫規範，即 headline-style + sentence-style。需要說明的是，這兩種 style 的組合使用並不是「混用」，而是有嚴格區分的：頁面標題（一級標題）採用 headline-style，文內標題採用 sentence-style。

之所以最終選擇此種大小寫規範，主要考慮以下幾點：

1. Google Cloud Spanner 的文檔閱讀體驗不錯，清晰無混搭雜亂之感。
2. 兩種 style 組合使用，可以讓頁面標題和文內標題的區分更加明顯，閱讀頁面內容時不易混淆。
3. 結合當前行業書面規範與實際使用現狀，不必拘泥於傳統的廣為人知但實際應用率不高的行業規範。
4. 發揮主觀能動性，做決定！哈哈……

不要忘了，如有任何技術傳播相關的問題或不同見解，歡迎在文末隨意留言哦！

References

DB-Engines Ranking 排名前十的資料庫文檔參考鏈接：

1. Oracle

• https://docs.oracle.com/en/database/
• https://docs.oracle.com/en/database/oracle/oracle-database/12.2/cncpt/data-concurrency-and-consistency.html#GUID-E8CBA9C5-58E3-460F-A82A-850E0152E95C

2. MySQL

• https://dev.mysql.com/doc/
• https://dev.mysql.com/doc/refman/5.7/en/backup-types.html

3. Microsoft SQL Server

• https://docs.microsoft.com/en-ie/sql/sql-server/sql-server-technical-documentation
• https://docs.microsoft.com/en-ie/sql/sql-server/install/network-protocols-and-network-libraries

4. PostgreSQL

• https://www.postgresql.org/docs/
• https://www.postgresql.org/docs/10/static/config-setting.html

5. MongoDB

• https://docs.mongodb.com/manual/
• https://docs.mongodb.com/manual/tutorial/upgrade-revision/

6. DB2

• https://www.ibm.com/support/knowledgecenter/SSEPGG
• https://www.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.qb.server.doc/doc/c0024080.html

7. Microsoft Access

• https://msdn.microsoft.com/en-us/library/office/ff604965.aspx
• https://msdn.microsoft.com/en-us/library/office/ff193164(v=office.14).aspx

8. Cassandra

• http://cassandra.apache.org/doc/latest/
• http://cassandra.apache.org/doc/latest/operating/index.html

9. Redis

• https://redis.io/documentation
• https://redis.io/topics/data-types-intro

10. Elasticsearch

• https://www.elastic.co/guide/index.html
• https://www.elastic.co/guide/en/elasticsearch/reference/current/accessing-data-in-pipelines.html
• https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html

你可能想讀：

技術寫作實例解析 | 簡潔即是美

兩分鐘趣味解讀 Technical Writer

若脫離理解，直譯得再正確又有何意？

深度解析關於技術翻譯的六個認知誤區

如何讓你的內容輸出更加專業更有設計感？

技術翻譯需要有 Technical Writer 的 sense

書單 | 有哪些技術傳播從業者必知必看的書籍？

有哪些適合技術傳播從業者關注的優質博客？（一）

有哪些適合技術傳播從業者關注的優質博客？（二）

如何使用正則表達式批量添加和刪除字元？

Markdown：超適合寫作的輕量級標記語言

如何為 Markdown 文件自動生成目錄？

優質譯文不應止於正確，還要 Well-Organized

寫在入職技術型創業公司 PingCAP 一個月之後

揭秘 Technical Writer 的工作環境 | 加入 PingCAP 五個月的員工體驗記

-END-