1、技術文檔寫作規范(Markdown)
標題分為四級。
下面是示例。
（1）一級標題下，不能直接出現三級標題。
示例：下面的文章結構，缺少二級標題。
（2）標題要避免孤立編號（即同級標題只有一個）。
示例：下面的文章結構， 二級標題 A 只包含一個三級標題，完全可以省略 三級標題 A 。
（3）下級標題不重復上一級標題的名字。
示例：下面的文章結構，二級標題與下屬的三級標題同名，建議避免。
（4）謹慎使用四級標題，盡量避免出現，保持層級的簡單，防止出現過於復雜的章節。
如果三級標題下有並列性的內容，建議只使用項目列表（Item list）。
示例：下面的結構二要好於結構一。後者適用的場景，主要是較長篇幅的內容。
全形中文字元與半形英文字元之間，應有一個半形空格。
全形中文字元與半形阿拉伯數字之間，有沒有半形空格都可，但必須保證風格統一，不能兩種風格混雜。
半形的百分號，視同阿拉伯數字。
英文單位若不翻譯，單位前的阿拉伯數字與單位間不留空格。
半形英文字元和半形阿拉伯數字，與全形標點符號之間不留空格。
1、盡量不使用被動語態，改為使用主動語態。
2、不使用非正式的語言風格。
3、不使用冷僻、生造或者文言文的詞語，而要使用現代漢語的常用表達方式。
4、用對「的」、「地」、「得」。
5、使用代詞時（比如「其」、「該」、「此」、「這」等詞），必須明確指代的內容，保證只有一個含義。
6、名詞前不要使用過多的形容詞。
7、不包含任何標點符號的單個句子，或者以逗號分隔的句子構件，長度盡量保持在 20 個字以內；20～29 個字的句子，可以接受；30～39 個字的句子，語義必須明確，才能接受；多於 40 個字的句子，在任何情況下都不能接受。
8、同樣一個意思，盡量使用肯定句表達，不使用否定句表達。
9、避免使用雙重否定句。
英文原文如果使用了復數形式，翻譯成中文時，應該將其還原為單數形式。
外文縮寫可以使用半形圓點( . )表示縮寫。
表示中文時，英文省略號（ ⋯ ）應改為中文省略號（ …… ）。
英文書名或電影名改用中文表達時，雙引號應改為書名號。
第一次出現英文詞彙時，在括弧中給出中文標注。此後再次出現時，直接使用英文縮寫即可。
專有名詞中每個詞第一個字母均應大寫，非專有名詞則不需要大寫。
引用第三方內容時，應註明出處。
使用外部圖片時，必須在圖片下方或文末標明來源。
數字一律使用半形形式，不得使用全形形式。
數值為千位以上，應添加千分號（半形逗號）。
對於 4 ～ 6 位的數值，千分號是選用的，比如 1000 和 1,000 都可以接受。對於7位及以上的數值，千分號是必須的。
多位小數要從小數點後從左向右添加千分號，比如 4.234,345 。
貨幣應為阿拉伯數字，並在數字前寫出貨幣符號，或在數字後寫出貨幣中文名稱。
表示數值范圍時，用 ～ 連接。參見《標點符號》一節的「連接號」部分。
帶有單位或百分號時，兩個數字都要加上單位或百分號，不能只加後面一個。
數字的增加要使用「增加了」、「增加到」。「了」表示增量，「到」表示定量。
數字的減少要使用「降低了」、「降低到」。「了」表示增量，「到」表示定量。
不能用「降低N倍」或「減少N倍」的表示法，要用「降低百分之幾」或「減少百分之幾」。因為減少（或降低）一倍表示數值原來為一百，現在等於零。
中文語句中的結尾處應該用全形句號（ 。 ）。
句子末尾用括弧加註時，句號應在括弧之外。
逗號 ， 表示句子內部的一般性停頓。
注意避免「一逗到底」，即整個段落除了結尾，全部停頓都使用逗號。
句子內部的並列詞，應該用全形頓號( 、 ) 分隔，而不用逗號，即使並列詞是英語也是如此。
英文句子中，並列詞語之間使用半形逗號（ , ）分隔。
分號 ； 表示復句內部並列分句之間的停頓。
引用時，應該使用全形雙引號（ 「 」 ），注意前後雙引號不同。
引號裡面還要用引號時，外面一層用雙引號，裡面一層用單引號（ 『 』 ），注意前後單引號不同。
補充說明時，使用全形圓括弧 （） ，括弧前後不加空格。
全形冒號（ ： ）常用在需要解釋的詞語後邊，引出解釋和說明。
表示時間時，應使用半形冒號（ : ）。
省略號 …… 表示語句未完、或者語氣的不連續。它占兩個漢字空間、包含六個省略點，不要使用 。。。 或 ... 等非標准形式。
省略號不應與「等」這個詞一起使用。
應該使用平靜的語氣敘述，盡量避免使用感嘆號 ！ 。
不得多個感嘆號連用，比如 ！！ 和 !!! 。
破折號 ———— 一般用於進一步解釋。
破折號應占兩個漢字的位置。如果破折號本身只佔一個漢字的位置，那麼前後應該留出一個半形空格。
連接號用於連接兩個類似的詞。
以下場合應該使用直線連接號（ - ），佔一個半形字元的位置。
以下場合應該使用波浪連接號（ ～ ），佔一個全形字元的位置。
注意，波浪連接號前後兩個值都應該加上單位。
波浪連接號也可以用漢字「至」代替。
軟體手冊是一部完整的書，建議採用下面的結構。
下面是兩個真實範例，可參考。
文檔的文件名不得含有空格。
文件名必須使用半形字元，不得使用全形字元。這也意味著，中文不能用於文件名。
文件名建議只使用小寫字母，不使用大寫字母。
為了醒目，某些說明文件的文件名，可以使用大寫字母，比如 README 、 LICENSE 。
文件名包含多個單詞時，單詞之間建議使用半形的連詞線（ - ）分隔。
查看原文
2、文檔工程師的工作內容是什麼？
作為一名文檔工程師，首先你要了解自己公司產品的性能，完全掌握和理解產品的用途和功能，這樣你寫出來的文檔才能讓別人信服。其次，需要掌握的簡單技能，比如會使用Dreamweaver，熟練使用辦公軟體（大多數人都覺得對辦公軟體很在行，可是能夠編輯出自己的模板，熟練寫出宏代碼之類的才真正算得上能熟練使用）。因為做文檔工作很枯燥，所以還需要有一顆穩得住的心。
加油吧，誠懇地面對你的面試官，記得帶上微笑，預祝你面試成功。
3、技術寫作理論知識- DITA
在早期，技術文檔寫作方式更其他文檔沒什麼區別，都是線性的寫作方式，一般一個產品對應一本文檔，隨著科技行業的日益發展，技術文檔寫作需求越來越多，一個產品往往有多個系列，像同一款汽車，有高中低三種配置，他們大部分是相同，只有少部分不同，如果按照線性的寫作方式，要寫三回，當然有人會說肯定沒這么傻，寫三回，肯定 and paste，這種方式同樣帶來問題，就是如果修改會至少要改三個地方，常常容易出錯。
針對這種問題，模塊化的寫作方式應運而生，DITA就是其中的佼佼者。DITA（Darwin Information Typing Architecture）是一種基於XML語言和信息分類的資料開發方法。利用DITA的資料開發方法，可以很好的解決同源和重用問題。
DITA最早有IBM提出，現今已經標准化，具體可以參見 https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
目前市場上用的最多的DITA寫作工具就是 Arbortext 了，基於XML語言，寫作與樣式分離。
使用DITA的方法開發文檔的流程一般式這樣：
從上圖我們可以很直觀的看出Topic可以被不同的Map引用，從而做到同源和重用，而Topic不決定發布件的格式，能夠做到內容與樣式分離。
InfoMapping是一個用於 分析、組織和表達 信息的 原則、技術和標準的集合 。
DITA是一種基於XML的文檔開發方法。
個人理解DITA是資料工程方法，是術，InfoMapping是信息理論，是道。兩者結合起來，就是技術文檔寫作的理論基石。
4、技術文檔誕生記 | 完整的技術寫作流程是怎樣的？
如果你有過 Technical Writer 實習或工作經歷，那麼對技術寫作的流程應該已經了解。當然，在很多大公司里，你參與的很可能只是這個流程的某一個環節。例如，你只負責寫，或者只負責 review，或者只負責文檔架構。相比之下，在創業公司里，可能會參與多個環節。
如果你是尚未畢業而且也沒有相關實習經歷的在校生，或者已經工作但有意轉行做 Technical Writer 的小夥伴，那麼可能對技術寫作流程仍存疑惑，或者一知半解。
不同公司技術文檔流程的劃分可能略有差異，但從本質上來看，則大同小異。無論你在這個流程中的哪個環節，從宏觀上了解整個流程有助於讓你的認識更加清晰，也有助於在有需求時從容地承擔其它環節的工作。
這里跟大家分享一個完整的技術文檔寫作流程，你只需記住六個單詞即可。如下圖所示：
再說明一下，你從工作中已經了解或即將接觸的技術寫作流程不一定與上圖完全一致，但一個完整的流程一般都會涵蓋這些內容，區別多半是主觀劃分而已，這一點不必拿出「大家來找茬」的精神死磕哦~
准備階段的工作主要包括以下幾點：
在寫文檔之前，需要明確文檔需求。你要了解為什麼要寫這篇文檔，寫這篇文檔是為了達到什麼目的。
也要明確文檔受眾。受眾不同，內容就很可能不同。比如，面向開發人員和非開發人員/普通用戶的文檔，在內容的組織上就會不同。
還要界定文檔范圍。思考並確定這篇文檔需要覆蓋哪些內容或模塊，以及不會涉及哪些內容。這樣在之後搜集資料的時候就會有所側重，寫的時候也不會模糊不定。
有過技術文檔寫作經歷的小夥伴一定會深有同感，如果不理解某個東西，那麼給它寫文檔簡直太痛苦。
那麼當遇到一個讓你毫無頭緒的陌生主題時，該如何盡量避免這種痛苦呢？當然就是盡最大可能去理解了。
可是具體該如何做呢？簡言之，即搜集資料。那又該如何搜集資料呢？筆者認為，可以從以下幾點著手：
1）對比較有代表性的同類產品或相似產品的相關文檔進行調研，看看別人的文檔是怎麼做的。
在一無所知的時候，借鑒他人的經驗做法不失為一種好的選擇。通過對幾家產品的文檔進行對比，你就可以對自己要寫的文檔建立一個大致的框架。
需要注意的是，借鑒不是照搬，只用於提供思路；產品不同，文檔的結構規劃也會有差異。
2）採用最有效的方法盡力搜集與所寫文檔相關的各種資料。
搜集的資料經過 Technical Writer 的摘刪組織，很可能就會成為發布文檔的一部分。
搜集資料的方法有很多，像網路搜索、調查問卷、訪談、實驗，以及郵件討論、報告、技術文章等等。到底該使用哪種方法要具體分析，需要你根據文檔需求、Deadline、已有資料的豐富程度等因素，來選擇能快速而准確地搜集到所需資料的方法。
有些主題的寫作，通過網路搜索可能幾乎無法給你提供任何幫助。即便是這類內容，你也可以從開發人員那裡獲得一些資料，可以根據自己的需求請他們協助提供資料，抑或是通過內部系統中的開發說明和討論獲取所需信息。
對於軟體類的產品文檔，即便有了一些技術資料，也往往需要 Technical Writer 自己使用一遍，從而對操作步驟有一個直觀的理解，獲得文檔寫作的一手資料。
當資料搜集得差不多的時候就可以組織這篇文檔的具體結構了，之前對相似產品的調研或許可以在此時助你一臂之力。
對於常見的產品使用指南，一般按照安裝或使用的順序進行組織；對於其它一些非指南類的文檔，也應遵循一定的順序或邏輯。
此外，還需考慮該文檔是否需要配圖，是否需要使用表格。如果需要配圖，明確是需要他人協助提供，還是需要自己完成。畫一個較復雜的圖也是一件蠻耗時的事情，花費的時間也需考慮在內。
有了詳細的文檔架構之後，就可以進行下一步的寫作了。
如果做好了前幾步的工作，寫作將變得非常簡單，你只需把相應的內容准確地填到文檔架構中。在這個過程中，你需要寫一個個段落或者具體的操作步驟。這是一個反映你的語言和寫作功底的時刻。
有的 Technical Writing 書籍中說到，在寫文檔的時候不必在意語法、措辭和標點，認為這些細節應該在 Revision 階段完善。
我對此有不同的看法。一個合格的 Technical Writer 本身應該有良好的語言功底，像語法、措辭和標點這種最基礎的細節本就不該成為一個需要單獨解決的問題。規范的語法、得體的措辭、正確的標點應該已經成為一種不需要額外付出精力、也幾乎不會佔用額外時間的寫作習慣。
如果寫作的初稿比較粗糙，有許多需要修改的小細節，這必定會增大 review 時的工作量和時間成本，從而延緩文檔流程。
或許，對於有精細化分工、每個人只負責一個小環節的大企業，可以採用這種方法。但是，對於快速發展、需要文檔敏捷開發的創業公司，這種就不適用了。
寫完文檔第一稿後，一般都需要進一步修改完善。這里的 Revision 指的是 review 之後的修改，所以這一步也可以叫作： Review & Revision 。
那麼需要誰來 review 呢？技術文檔通常需要請其他小夥伴進行兩種 review，即：
收到 reviewer 的反饋之後，Technical Writer 需要及時作出判斷和修改，有不明確的地方需和 reviewer 討論確定。改完之後，再請 reviewer 看一下。如果又發現了新的問題，那麼還需要再次修改。這個 review - revise 的過程可能會反復幾次，很正常。
當然，在請他人 review 之前，Technical Writer 也可以先自己 review 一遍，盡量避免低級錯誤，不浪費他人的時間。
哈哈，問題又來了~通常，剛寫完一篇文章的人是很不情願再去看自己寫的東西的，此時就可以使用一些語法拼寫檢查的小工具來協助你了。
我在之前的一篇文章 Technical Writer 日常工作中好用的小工具 中有推薦，有需要的小夥伴可以戳鏈接去瞅瞅~
如果你覺得自己足夠細心，根本不需要小工具來協助你，我佩服你的能力，但還是建議用一下小工具。因為，你可能也會有狀態不好的時候，有疲勞打盹的時候，有不知道自己寫了一堆什麼鬼東西的時候……不要跟自己和小工具過不去。
等文檔定稿之後，就可以在平台上發布了，一般很容易操作。不同的公司的文檔發布平台也會不一樣，Technical Writer 使用的寫作工具也不一樣。
文檔發布之後，並不代表著結束。根據我的工作經歷，即便是已經發布的文檔，也依然有可能存在問題，無論是大公司還是小公司的文檔。例如：未發現的文字錯誤、失效的鏈接、與最新的產品已不匹配的描述和步驟等。Technical Writer 需要及時跟進產品動態，以便及時更新文檔。
寫技術文檔不是一勞永逸的，只要產品在更新，就需要 Technical Writer 一直維護下去。
以上分享的是一個完整的技術文檔從零到有的過程。日常工作中，有時不需要從頭開始，而只是對原有文檔的增刪修改，那就可以省去一些相應的環節。
如果你也是一枚 Technical Writer，也期待聽到你對技術寫作流程的見解，歡迎留言交流哦~
Reference:
你可能想讀 ：
Technical Writer 日常工作中好用的小工具
技術翻譯需要有 Technical Writer 的 sense
深度解析關於技術翻譯的六個認知誤區
如何讓你的內容輸出更加專業更有設計感？
書單 | 有哪些技術傳播從業者必知必看的書籍？
有哪些適合技術傳播從業者關注的優質博客？（一）
有哪些適合技術傳播從業者關注的優質博客？（二）
經驗分享 | 來自 11 位 Technical Writer 前輩的職業發展建議（上篇）
經驗分享 | 來自 11 位 Technical Writer 前輩的職業發展建議（下篇）
英語技術文檔的標題到底該大寫還是小寫？
如何使用正則表達式批量添加和刪除字元？
Markdown：寫技術文檔、個人博客和讀書筆記都很好用的輕量級標記語言
如何為 Markdown 文件自動生成目錄？
技術寫作實例解析 | 簡潔即是美
兩分鍾趣味解讀 Technical Writer
若脫離理解，直譯得再正確又有何意？
優質譯文不應止於正確，還要 Well-Organized
寫在入職技術型創業公司 PingCAP 一個月之後
揭秘 Technical Writer 的工作環境 | 加入 PingCAP 五個月的員工體驗記
-END-