為友善檢視，使用Google翻譯從 Google開發人員文檔樣式指南 搬運而來
一般原則
風格和作者的語氣
https://developers.google.cn/style/tone
交談而不輕浮。
在你的檔案中，要有一個對話，友善和尊重的聲音和語氣，不要過于口語或輕;; 一種随意，自然而平易近人的聲音，而不是迂腐的或激進的。嘗試聽起來像一個懂得開發者想要做什麼的知識淵博的朋友。
不要試圖寫出你說話的方式; 你可能比你應該寫更多的口頭和口頭上說，至少開發文檔。但目标是一個會話語氣，而不是一個正式的。
不要試圖超娛樂，也不要超幹。做人，讓你的個性展現，令人難忘; 你甚至可以有點搞笑。但請記住，該文檔的主要目的是向正在尋找它的人提供資訊。
請記住，許多讀者不是英語母語人士，他們中的許多人來自不同于您的文化，您的文檔可能會翻譯成其他語言。
有些事情要盡可能避免
- 流行語或技術術語。
- 太可愛了。
- “請注意”和“此時”的占位符短語。
- 啰嗦或冗長的句子。
- 用相同的短語開始所有句子（如“你可以”或“待辦事項”）。
- 目前的流行文化參考。
- 以顧客，競争對手或其他人為代價的笑話。
- 驚歎号，除了在罕見的真正激動人心的時刻。
- 貪婪，僵硬和愚蠢。
- 混淆隐喻或隐喻太多。
- 有趣的線條與主題沒有密切的關系，或者需要大量的主題詞，或者模糊資訊。
- 诋毀或侮辱任何一群人的措辭。
- 用“讓我們”來表達一些措辭。
- 在程式中使用“簡單”或“這麼簡單”或“很容易”等短語，除非是非常簡單/容易的程式。
一些技術和方法來考慮
- 如果你在表達一些東西時遇到困難，請退後問自己：“我想說什麼？通常，你給自己的答案揭示了你應該在檔案中說什麼。
- 如果你不确定你的措辭或語氣，請一位同僚來看看。
- 試着大聲閱讀你的檔案的部分，或至少說話的話。這聽起來自然嗎？不是每個句子在說話時都必須聽起來自然，這些是書面檔案。但是，如果你遇到一句尴尬或混亂的句子時，考慮一下你是否可以使它更加交談。
-
使用句子之間的轉換。像“雖然”或“這種方式”這樣的短語可以使段落更加低調。（再次，有時像“然而”或“然而”這樣的過渡可以使段落更加高調）。
即使遇到問題，也要確定以清晰直接的方式交流有用資訊。這是最重要的部分。
禮貌和使用“請”
禮貌是很好的，但在一組訓示中使用“請”是禮貌的過度。
不建議：要檢視文檔，請點選檢視。
建議：要檢視文檔，請單擊 檢視。
也：
不建議：有關更多資訊，請參閱[連結到其他文檔]。
建議：有關更多資訊，請參見[連結到其他文檔]。
例子
| 太不正式了 | 恰到好處 | 太正式了 |
|---|---|---|
| 好家夥！這API是完全可怕的！ | 這個API可以讓你收集你的使用者喜歡的資料。 | 該頁面記錄的API可以使得能夠擷取關于使用者偏好的資訊。 |
| 就像一個流行明星一樣，這個電話會得到你的“電話”号碼。問問别人的數字的簡單方法！ | 要獲得使用者的電話号碼，請緻電 。user.phoneNumber.get() | 電話号碼可以由開發者通過簡單的get()方法在user 對象phoneNumber屬性上使用方法來檢索。 |
| 然後，BOOM ，就像他們用法語說的那樣，隻是垃圾收集（或者說集裝箱裝扮），而你是金的。 | 要清理，請調用該collectGarbage()方法。 | 請注意，完成任務需要以下先決條件：執行自動記憶體管理功能。 |
記錄未來的功能
https://developers.google.cn/style/future
不要在文檔中預先釋出任何内容。
避免試圖記錄未來的功能或産品，即使以無害的方式。
可通路的内容
https://developers.google.cn/style/accessibility
撰寫不僅可供殘障人士士使用的檔案，也可向國際閱聽人以及使用舊技術和不同浏覽器的使用者提供檔案。
- 使用正确的文法和标點符号。
- 使用主動語态和現在式。
- 寫清楚，簡單的句子。
- 始終如一。
- 避免行話，俚語等。
例子
不推薦： API選擇器列出了您可能想要做的最常見的事情。
建議： API選擇器列出了您可能想要執行的最常見的事情。
- 使用最簡單的術語。
- 明智地使用顔色：
- 請記住，一些色盲的人不能告訴綠色的紅色。
- 確定您的文字顔色與您的背景顔色充分對比。
為全球讀者撰寫
https://developers.google.cn/style/translation
我們用美國英語編寫我們的開發者文檔，但其中一些被翻譯成英文以外的語言。寫在筆記翻譯。
幾個具體的建議：
寫簡短的，明确的句子。
句子越短，翻譯就越容易。英語比大多數語言短; 平均長度的英文句子翻譯時可能會導緻很長的句子，影響了了解。
始終如一。
例如，如果您在一個地方使用特定概念的特定術語，則在其他地方使用完全相同的術語，包括相同的大寫。如果你使用不同的名字來做同樣的事情，翻譯者可能會認為你指的是不同的概念，是以可能會使用不同的翻譯。
另外，不要用同一個詞來表示不同的東西。尤其要避免在近距離使用同一個詞作為名詞和動詞。有關多重含義問題的示例，請參閱單詞清單條目一次和以後。
避免縮寫。
縮略語可能會混淆背景，而且翻譯不好。至少在第一次使用給定的術語時，盡可能地拼出一些東西。
不要使用太多的修飾符。
特别是，不要使用兩個以上的名詞作為另一個名詞的修飾語。
避免錯位修飾符。
例如，在與其相關的名詞或動詞的前面加上“only”或“just”等單詞。
不推薦：開發人員隻需要申請一個令牌。
建議：開發人員隻需要申請一個令牌。
澄清前因。
當譯員使用小而不連貫的文本串時，使用代詞可能會變得棘手。通過盡可能清楚的事情來幫助他們。例如，如果代詞含糊不清，則用适當的名詞來代替它。
不推薦：如果您在廣告中使用“綠色啤酒”一詞，請確定它是有針對性的。
建議：如果您在廣告中使用“綠色啤酒”一詞，請確定廣告有針對性。
不要太具體的文化。
特别是，除非你确定他們是世界聞名的，否則不要提到具體的假期，文化習俗，運動等等。
也避免口語化。諸如“棒球形狀”，“背部燃燒器”或“懸挂在那裡”這樣的短語可能會令人困惑。
語言和文法
縮略語
https://developers.google.cn/style/abbreviations
縮寫包括首字母縮略詞，初始主義，縮寫詞和縮寫。
- 首字母縮寫詞是由短語中的第一個字母組成的，但發音就像是一個詞本身：
- 北約對北大西洋公約組織。
- 水肺為自含式水下呼吸器。
- 初始化也是由一個短語中的第一個字母組成，但每個字母都是分開發音的：
- CIA為中央情報局。
- 供參考的資訊。
- PR的公共關系。
- 縮短的單詞隻是一個單詞或短語的一部分，有時在最後一段時間：
- 醫生為醫生。
- 等對等等。
- 分鐘的分鐘。
- CA為加州。
- 收縮在本樣式指南的單獨頁面中讨論。
這些類别之間有一些重疊。具體而言，取決于說話者的偏好，一些縮寫可以是縮寫詞或初始詞; 例子包括FAQ和SQL。在某些情況下，發音決定使用“a”還是“an”。
主動語态
https://developers.google.cn/style/voice
明确誰在執行行動。
一般來說，使用主動語态（其中句子的文法主體是進行動作的人或事物）而不是被動語态（其中句子的文法主體是被操縱的人或事物），雖然有例外。
其中一個原因是：在被動語态中，很容易忽略指出誰或什麼正在執行特定的動作; 在這種建構中，讀者往往很難弄清楚誰該做什麼。（讀者，計算機，伺服器，最終使用者，網頁通路者......）
例子
不推薦：查詢服務，發送确認。
建議：發送一個查詢到服務。伺服器發送确認。
可以用被動語态（用“by”）來表示誰在執行動作，但是由此産生的散文通常不如将句子重寫為主動語态那麼好。是以隻要有可能，就把這個行為當作句子的主語。
例子
不建議：服務由您查詢，并由伺服器發送确認。
建議：發送一個查詢到服務。伺服器發送确認。
拟人論
https://developers.google.cn/style/anthropomorphism
不要将人的品質歸因于軟體或硬體。
例子
不推薦：定界符對象告訴拆分器應該斷開一個字元串的位置。
建議：分隔符對象指定分隔字元串的位置。
不推薦：PC看到一個新的裝置。
建議：PC檢測到新裝置。
文章（a，an，the）
https://developers.google.cn/style/articles
在文檔中包含明确和不确定的條款，并正确使用它們。
為了便于了解和翻譯，在你的寫作中包括一個，一個和 一個。
一和的是不定冠詞和單數名詞之前使用。他們指的是任何一個組的成員。
這是一個明确的文章。它在單數和複數名詞之前使用，指一個或多個特定的成員。
是否使用“a”或“an”取決于後面的單詞的發音。在輔音之前使用“a”; 在任何元音之前使用“an”。
例子
- 一小時。
- 一個HTML檔案。
- 一隻手。
- 一家酒店。
- 一把雨傘。
- 工會。
更複雜的是，一些縮寫既可以是縮寫和initialisms，需要一個在一個執行個體，一個在其他。例如，常見問題解答，其中一些讀“斑”和其他人拼出來，需要的時候拼寫和一個當作為單詞發音。以下是這些類型縮寫的清單，以及我們對哪些文章的使用建議：
- 一個SQL（資料庫）。
- 常見問題解答
大寫
https://developers.google.cn/style/capitalization
在文本中，遵循美國英語的标準大寫規則。另外：
- 不要使用全部大寫字母來強調。
- 請遵循官方名稱，品牌，公司，軟體，産品，服務等的名稱。
注意：有關如何大寫特定單詞的資訊，請參閱單詞清單。
标題和标題的大小寫
在檔案标題和頁面标題中，使用句子大小寫。也就是說，隻是把第一個字大寫。
例外：對于專有名詞，商标，關鍵字和其他總是以某種方式進行大寫的術語，使用該術語的标準大寫，而不管它在标題或标題中出現的位置。
即使你正在使用判例，也不要在标題末尾加上句号。
大寫和冒号
使用小寫字母開始緊跟在冒号後面的文本的第一個單詞，除非文本是以下内容之一：
- 專有名詞
- 一個報價。
- 項目符号，編号或定義清單中的項目。
- 跟在标簽之後的文本，例如注意或注釋。
- 與标題相同的行上的副标題。
大寫和數字
使用字幕和其他與人物相關的文字。
術語表和索引中的大寫
詞彙和索引術語使用小寫，除非該術語是專有名詞，或者有其他原因需要大寫。
詞彙表定義使用句子。
大寫和連字
當一個帶連字元的單詞是一個句子或一個标題中的第一個單詞時，除非後面的單詞是專有名詞或适當的形容詞，否則隻用大寫單詞中的第一個單詞。
清單中的大寫
對所有類型的清單中的項目使用句子大小寫。
文本中表格的大小寫
對表格中的所有元素使用句子：内容，标題，标簽和标題。
子句順序
https://developers.google.cn/style/clause-order
在說明之前放置有條件的條款，而不是在之後。
假設你想告訴觀衆在特定情況下做些事情。如果可能的話，請在提供指導之前提及情況; 這樣，如果情況不适用，讀者可以跳過這個指令。
例子
不建議：請參閱[連結到其他文檔]了解更多資訊。
建議：有關更多資訊，請參見[連結到其他文檔]。
不建議：如果要删除整個文檔，請單擊“ 删除”。
建議：要删除整個文檔，請單擊删除。