英语技术文档的标题到底该大写还是小写？

温馨提醒：点击文中配图可放大查看清晰大图。

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 you're using sentence case, don't 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 排名，对数据库产品的文档进行了一个关于大小写规范的小调查。

2018 年 1 月排名

那么问题来了，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.

大小写规范的调查结果如下表所示：

排名	数据库	大小写规范
1	Oracle	Headline-style
2	MySQL	Headline-style
3	Microsoft SQL Server	Headline-style
4	PostgreSQL	Headline-style
5	MongoDB	Headline-style
6	DB2	Sentence-style
7	Microsoft Access	Headline-style
8	Cassandra	Headline 和 sentence 两种 style 混用
9	Redis	Headline 和 sentence 两种 style 混用
10	Elasticsearch	Headline 和 sentence 两种 style 混用

注：上表统计为某个产品文档总体的大小写风格，如果在 Headline-style 中夹杂着个别 sentence-style 或者疏漏导致的大小写不一致，不计入此表。

上表中均已附上链接，为了让大家快速直观地理解，下面上几个比较有代表性的图：

Oracle headline-style

MySQL headline-style

Microsoft SQL Server headline-style

PostgreSQL headline-style

MongoDB headline-style

Cassandra 两种 style 混用

Elasticsearch 两种 style 混用之 headline-style

Elasticsearch 两种 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 的 sense
深度解析关于技术翻译的六个认知误区
如何让你的内容输出更加专业更有设计感？
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？（一）
有哪些适合技术传播从业者关注的优质博客？（二）
如何使用正则表达式批量添加和删除字符？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
如何为 Markdown 文件自动生成目录？
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
优质译文不应止于正确，还要 Well-Organized
写在入职技术型创业公司 PingCAP 一个月之后
揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记

-END-