Foreword
之前跟大家分享過英語技術(shù)文檔中如何正確使用時態(tài)和英語技術(shù)文檔中如何正確使用人稱沉噩，這一篇再跟大家分享一下如何正確使用無序列表和有序列表捺宗。
其實，在技術(shù)文檔中川蒙，除了無序列表和有序列表蚜厉，另一種常見的列表是定義列表 (Definition list，Google 的 Style Guide 中稱作 Description list)畜眨。定義列表的使用注意規(guī)范即可昼牛，相對簡單，本文暫不作展開康聂，主要聊一聊無序列表和有序列表贰健。
你可能會說了，無序列表和有序列表很容易分清啊恬汁，無順序要求的用無序列表伶椿，有順序要求的用有序列表就好了。確實，是這么個邏輯脊另。但問題在于导狡，有時你不知道它是無序的還是有序的。
筆者在工作中發(fā)現(xiàn)偎痛，英語技術(shù)文檔中列表的使用可能會出現(xiàn)以下問題：
- 不清楚使用情境旱捧，不該用列表的地方卻用了。
- 誤用列表踩麦，無序列表和有序列表選擇錯誤枚赡。
- 選對了列表，但在大小寫谓谦、標(biāo)點等格式上不規(guī)范标锄。
于是，筆者研究了下 IBM 和 Google 的文檔規(guī)范中對有序列表和無序列表的說明茁计，在這里分享給大家料皇。本文談到的基本規(guī)范是通用的，有一些具體的格式是基于 GitHub + Markdown 這種文檔解決方案來說的星压，相關(guān)之處會詳細(xì)說明践剂。本文結(jié)構(gòu)如下：
- 什么是無序列表和有序列表
- 為什么要規(guī)范使用列表
- 何時使用無序列表
- 何時使用有序列表
- 常用的列表格式規(guī)范
1. 什么是無序列表和有序列表
-
無序列表，即 Unordered lists 或 Bulleted lists娜膘。百度百科里對它的定義為：
無序列表是一個沒有特定順序的列表項的集合逊脯，也稱為項目列表。在無序列表中竣贪，各個列表之間屬于并列關(guān)系军洼，沒有先后順序之分，它們之間以一個項目符號來標(biāo)記演怎。
有序列表匕争，即 Ordered lists 或 Numbered lists。顧名思義爷耀，即有順序的列表甘桑，通常是用數(shù)字來標(biāo)示順序的列表，在技術(shù)文檔中常用于描述具體的操作步驟歹叮。
2. 為什么要規(guī)范使用列表
在技術(shù)文檔中跑杭，規(guī)范地使用無序列表和有序列表有助于幫助文檔讀者快速、正確咆耿、清晰地理解要傳達(dá)的意思德谅。而如果使用不當(dāng)，就可能會誤導(dǎo)讀者萨螺，給讀者造成困惑窄做，甚至理解錯誤宅荤，影響文檔和產(chǎn)品的使用體驗。
-
如果在本該使用無序列表的地方用了有序列表浸策，那么用戶可能會想：
看內(nèi)容感覺好像不存在順序關(guān)系冯键，可既然用了有序列表，是不是表明這些項之間存在優(yōu)先級關(guān)系或是先后順序呢庸汗？
-
如果在本該使用有序列表的地方用了無序列表惫确，那么用戶可能會想：
看列表格式好像是沒有順序關(guān)系，可是看內(nèi)容好像又應(yīng)該是有先后順序的蚯舱，到底是要表達(dá)怎樣的關(guān)系呢改化？或者，雖然不是有順序的操作步驟枉昏，但各項之間存在某種邏輯關(guān)系陈肛，也需要用有序列表來傳達(dá)，此時兄裂，如果用無序列表就會丟失這么一層關(guān)系句旱。
3. 何時使用無序列表
根據(jù) IBM Style Guide，當(dāng)列表項之間的順序不重要時晰奖，使用無序列表谈撒。根據(jù) Google 的 Style Guide，無序列表用于既非順序列也非選項的列表項匾南。
需要注意的是啃匿，即便在無序列表中，如果可能的話蛆楞，也應(yīng)該盡量按某種邏輯來展示各項溯乒。如果沒有更好的選擇，可以按字母順序來排列豹爹。
如果列表是有依據(jù)的分組裆悄，但該依據(jù)并非顯而易見，最好說明一下帅戒。
正確示例：
When you configure the computer, you can use the program to set the following items:
- Date and time
- Passwords
- Drive startup sequence
4. 何時使用有序列表
當(dāng)各項之間的順序很重要時灯帮，使用有序列表。相關(guān)的場景如下：
- 必須按順序操作的步驟（最常用）
- 對多項內(nèi)容進行的排名
- 列表項中的內(nèi)容是之后需要引用的規(guī)則或其它信息
前兩個場景比較好理解逻住，第 3 個場景常用于列表項為一些規(guī)則時，比如 4 條規(guī)則迎献，然后瞎访，在下文或其它文檔中需要引用該規(guī)則列表中的某項規(guī)則。此時有個數(shù)字編號就很方便引用了吁恍，通常列表中的第幾條對應(yīng)的就是規(guī)則幾扒秸，如列表中的第 3 條在引用時可以說“規(guī)則 3”播演。
正確示例：
Write comment statements according to the following rules:
- Use an asterisk in the first column.
- Do not exceed 80 characters.
- Do not place a comment statement between an instruction and its continuation line.
5. 常用的列表格式規(guī)范
現(xiàn)在大家已經(jīng)清楚了何時使用無序列表和有序列表，再來看看使用列表時還需注意的一些格式規(guī)范：
- 列表前的介紹性句子
- 列表內(nèi)容的大小寫
- 列表內(nèi)容的平行語法
- 列表項的標(biāo)點
- 列表的長度
- 列表項包含多個段落
- 列表嵌套
列表前的介紹性句子
大多數(shù)情況下伴奥，在列表前都需要有一個介紹性的句子写烤。
- 如果列表不是操作步驟，通常需要在列表前加一個介紹性的句子拾徙。
- 如果在 Task 類型的 topic 中洲炊，列表緊跟著 "Before you begin," "Prerequisites," "Restrictions,"，那么列表前可以加介紹性句子尼啡，也可以不加暂衡。
列表前的介紹性引入句子可以以冒號結(jié)束，也可以以句號結(jié)束崖瞭。通常狂巢，如果緊接著列表內(nèi)容，則使用冒號书聚；如果在介紹性句子和列表之間還有其它內(nèi)容（如注意事項）唧领，則使用句號。
錯誤示例：
Use the Submit button to:
- submit the form
- indicate that you're done
- allow the next person to enter their data
正確示例：
Use the Submit button for any of the following purposes:
- To submit the form.
- To indicate that you're done.
- To allow the next person to enter their data.
對于列表前的介紹性引入句子雌续，IBM 和 Google 的規(guī)范都建議盡量使用一個完整的句子疹吃，而非需要列表項才能補全的句子片段。例如西雀，以 To 開頭的不定式短語萨驶，可以使用，但不建議使用艇肴。
不建議使用：
To get the USB driver:
- Click Tools > Android > SDK Manager.
- Select Google USB Driver and then click OK.
建議使用：
To get the USB driver, follow these steps:
- Click Tools > Android > SDK Manager.
- Select Google USB Driver and then click OK.
列表內(nèi)容的大小寫
在垂直列表中腔呜，每個列表項第一個單詞的首字母需大寫，特殊情況除外再悼。
正確示例：
The routine makes the following conversions:
- An EBCDIC value to a real number
- A real number to an EBCDIC value
- An EBCDIC value to an integer
- An integer to an EBCDIC value
列表內(nèi)容的平行語法
在同一個列表中核畴，各列表項盡量使用相同的語法或結(jié)構(gòu)，或者說冲九，盡量讓各列表項在語法上保持平行谤草。例如，盡量做到要么各列表項都是完整的句子莺奸，要么都不是丑孩。
錯誤示例：
XYZ Manager has the following features:
- A graphical user interface.
- It is compatible with ABC Manager.
- It can be used on many types of systems.
正確示例：
XYZ Manager has the following features:
- It has a graphical user interface.
- It is compatible with ABC Manager.
- It can be used on many types of systems.
列表項的標(biāo)點
列表項末尾的標(biāo)點要根據(jù)列表類型和具體內(nèi)容而定。
- 如果列表項都是完整的句子灭贷，在末尾加句號温学。
- 如果列表項是一個短語，末尾不加標(biāo)點甚疟。
- 如果列表項不包含動詞仗岖，末尾不加標(biāo)點逃延。
- 如果列表項只包含一個詞，末尾不加標(biāo)點轧拄。
- 如果列表中的某個列表項以短語開頭揽祥，一個或多個短語之后緊接的是完整的句子。此時檩电，短語和完整句子后面都加句號拄丰。
錯誤示例：
Session management can store session-related information in several ways:
- In application server memory. This storage option is local to the application server and cannot be shared with other application servers.
- In a database
- In another WebSphere Application Server instance
正確示例：
Session management can store session-related information in several ways:
- In application server memory. This storage option is local to the application server and cannot be shared with other application servers.
- In a database.
- In another WebSphere Application Server instance.
列表的長度
- 有序列表中，需至少包含兩個列表項是嗜。
- 無序列表中愈案，如果是為了跟同一部分其它無序列表的格式保持一致，可以只包含一個列表項鹅搪。
- 列表不可過長站绪，根據(jù) IBM 的文檔規(guī)范，最多可包含 9 個列表項丽柿。如果列表項的數(shù)目超過了此限制恢准，可考慮使用多個列表。
- 如果是 Reference 文檔中按字母順序排列的列表甫题，那么列表較長也是可以接受的馁筐。因為用戶不會從頭讀到尾，而是會根據(jù)字母順序找到所需的部分坠非。
列表項包含多個段落
列表項可能包含多個段落敏沉，常見于對列表項的進一步解釋說明。例如：
This list item is a single paragraph.
This list item contains multiple paragraphs.
As you can see!
This is another list item that's only one paragraph long.
在 Markdown 文件中炎码，需注意多個段落前的空格縮進盟迟，通常為兩個或四個空格；還需注意給多的段落前添加空行潦闲，否則也很可能會影響格式的正確顯示攒菠。某個列表項所包含的段落，需與該列表項開始的內(nèi)容在格式上對齊歉闰。
筆者在使用 GitHub 和 Markdown 的實踐中辖众，通常會統(tǒng)一空四個空格，這樣無論是有序列表還是無序列表和敬，均可正確顯示格式凹炸。不同文檔發(fā)布平臺可能要求不同，知曉并遵守規(guī)范即可概龄。
列表嵌套
關(guān)于無序列表和有序列表中的嵌套列表还惠，IBM 要求盡量避免列表嵌套超過兩級，最多三級私杜。Google 規(guī)范中無明確說明蚕键，但通常最多三級。
在 Markdown 文件中衰粹，嵌套列表時需注意嵌套項的空格縮進锣光。不同的網(wǎng)站可能有不同的要求，例如嵌套的無序列表縮進兩個空格即可铝耻。
大多數(shù)情況下誊爹，如果嵌套項比上一級縮進四個空格，格式可正確顯示瓢捉。
正確示例 1：
Remove the cover.
Install the adapter:
- Insert the adapter into the slot.
- Connect the adapter cable to the connector on the system board.
Install the cover.
正確示例 2：
The following choices are on the menu:
- DPI settings
- Set Write Access Managers
- Set Trap Receivers
- Reset configuration
Afterword
除了上文提到的列表類型之外频丘，Google 的規(guī)范中還提到一種字母列表 (Lettered list)，指的是一些可供選擇的列表項泡态，尤其指互斥的選項搂漠。這類列表通常使用大寫的 A、B某弦、C桐汤、D 來展示各項，類似于試卷中常出現(xiàn)的選擇題靶壮。
看到這里怔毛，想必大家對技術(shù)文檔中無序列表和有序列表的使用有了更多的了解。如果你在技術(shù)文檔寫作的實踐或研究中有不同的見解腾降，或者想跟大家分享你使用列表的經(jīng)歷拣度，歡迎留言交流哦~
參考資料：
- IBM Style Guide
- Google Developer Documentation Style Guide: https://developers.google.cn/style
你可能想讀：
技術(shù)文檔誕生記 | 完整的技術(shù)寫作流程是怎樣的？
Technical Writer 可提供的交付物有哪些螃壤？
GitHub + Markdown 的新輕型技術(shù)寫作模式速覽
GitHub + Markdown 的技術(shù)文檔方案深度解析
Technical Writer 日常工作中好用的小工具
技術(shù)傳播人士應(yīng)該知道的色彩搭配常識
如何使用顏色來提高技術(shù)文檔的可讀性抗果？
Technical Writer 如何 Review 技術(shù)文檔？| 重細(xì)節(jié)+全局觀
技術(shù)翻譯需要有 Technical Writer 的 sense
深度解析關(guān)于技術(shù)翻譯的六個認(rèn)知誤區(qū)
如何讓你的內(nèi)容輸出更加專業(yè)更有設(shè)計感映穗？
書單 | 有哪些技術(shù)傳播從業(yè)者必知必看的書籍窖张？
有哪些適合技術(shù)傳播從業(yè)者關(guān)注的優(yōu)質(zhì)博客？（一）
有哪些適合技術(shù)傳播從業(yè)者關(guān)注的優(yōu)質(zhì)博客蚁滋？（二）
經(jīng)驗分享 | 來自 11 位 Technical Writer 前輩的職業(yè)發(fā)展建議（上篇）
經(jīng)驗分享 | 來自 11 位 Technical Writer 前輩的職業(yè)發(fā)展建議（下篇）
技術(shù)傳播沙龍精彩分享 | 高校老師與行業(yè)大牛談“互聯(lián)網(wǎng)技術(shù)寫作”
英語技術(shù)文檔的標(biāo)題到底該大寫還是小寫宿接？
不同階段如何應(yīng)對 Technical Writer 的職業(yè)顧慮或煩惱？
如何使用正則表達(dá)式批量添加和刪除字符辕录？
英語技術(shù)文檔中如何正確使用時態(tài)睦霎？
英語技術(shù)文檔中如何正確使用人稱？
Markdown：寫技術(shù)文檔走诞、個人博客和讀書筆記都很好用的輕量級標(biāo)記語言
如何為 Markdown 文件自動生成目錄副女？
技術(shù)寫作實例解析 | 簡潔即是美
兩分鐘趣味解讀 Technical Writer
若脫離理解，直譯得再正確又有何意蚣旱？
優(yōu)質(zhì)譯文不應(yīng)止于正確碑幅，還要 Well-Organized
Technical Writer 需要 Technical 到會寫代碼嗎戴陡？
如何利用 GitHub Pages 和 Hugo 輕松搭建個人博客？
寫在入職技術(shù)型創(chuàng)業(yè)公司 PingCAP 一個月之后
揭秘 Technical Writer 的工作環(huán)境 | 加入 PingCAP 五個月的員工體驗記
-END-
