關于文檔編寫的幾個思維
近期重新組織了好幾篇技術文檔，把其中的一些感悟提煉出來。
文檔為達到容易理解和操作的程度，對大量的語言重新組織，內容的不同呈現，借助輔助工具等一系列操作，本文就是剖析整個流程
全文主要的流程是：
- 編寫文檔前，準備工作有哪些？
- 根據現有文檔的問題是？
- 語言的組織和內容的不同呈現方式有哪些？
- 按照現有文檔完成后的文檔輸出如何組織？
0. 程序員如何看待文檔？
程序員一定會是接觸各種各樣的技術文檔，文檔寫的好與不好，大致都能區分出來。
但是對于自己寫的文檔卻可以容忍 “丑陋” 、“難以理解”等......
對技術、代碼可以修改、修改、再修改，優化、優化、再優化......
我覺得出現問題在于：程序員對于如何有效的邏輯表達以及優秀的排版沒有意識。
據我觀察，一個程序員完成了一份代碼的編寫，對文檔只會花小部分時間進行書寫，會自然而然的忽略部分信息，認為把信息堆砌出去，就是一篇文檔......
不不不，我認為不應該這樣......
但凡偉大的公司、產品對“呈現” 這一塊都絕對的重視。盡量都在簡化用戶的操作復雜程度，比如極度克制的微信。
1. 什么是好的文檔？
如何定義一份文檔是通俗意義上的好？
就個人的認識，可以從 GitHub 上的最熱門的開源項目的文檔入手？
比如個人最崇拜的世界 Python 技術排名第五的作者： kennethreitz，他的開源作品：requests
再比如：開源 web 框架 Django
這兩個項目的文檔堪稱是教科書式文檔示例。
閱讀這些項目的文檔，一定有個感官的認識：文檔寫的好，根據文檔能使用起來，整體文檔的風格也高度的統一。
一個好的文檔我認為具有下面三個特點：準確、清晰和美觀
準確和清晰對應邏輯梳理和表達。
美觀對應排版。
2. 編寫文檔的整體流程有哪些？
我現在的步驟是：
- 收集
- 梳理
- 實踐
- 編寫
2.1 收集
- 根據 wiki 收集現有的資料，以及相關故障的問題記錄文檔（其中已知的故障問題文檔很重要，這能讓你明白別人問題會出現在哪）
- 和原文檔編寫者溝通（也能讓你感性的認識到他口中的文檔的問題）
2.2 梳理
- 根據收集的到的資料，感性的認識到文檔的整體流程是什么，以及需要注意些什么
- 記錄：把已知問題進行記錄
梳理環節主要是關注現有文檔的整體流程以及你如何可以對現有流程優化
2.3 實踐
- 根據收集的資料和現有的文檔進行操作
- 注意你的出錯的點，以及你根據別人的提示避開的出錯的點
實踐環節主要是關注那些 ‘坑’，直到你成功的按照步驟得到理想的結果
2.4 編寫
現在手頭你已經有歷史經驗（收集的資料）和 實踐經驗（實踐環節）。
進行文檔的編寫需要注意兩個點：
- 邏輯表達、內容組織
- 排版
一篇文檔主要包含這些內容：
- 標題
- 文本
- 段落
- 圖片
- 表格
這里有一篇中文技術文檔寫作規范參考：阮一峰：中文技術文檔寫作規范
標題：
我只談論一點：標題原則上存在六級，即一級、二級、三級、四級、五級和六級標題。但我推薦使用前三級標題，其余的使用列表項目進行組織。因為層級組織多了，其實是并不太友好。
文本：
參考示例中講了很多，我值談論三點：
- 重點強調使用加粗處理，且重點強調的不應過長。比如你強調了幾百個字符，其實相當于沒起到強調的作用
- 注意中英文的處理：即英文和中文強化空一格。比如：English 英語
- 慎用斜體
段落：
我談論一點：
- 各段落中間使用換行處理。
- 一個段落不應過長，嘗試拆分成幾個段落。
圖片：
我談論兩點：
- 圖片的作用：即對一些文字不好描述的使用圖片視覺化呈現
- 圖片的大小：文檔內的圖片建議大小一致：即寬度和網頁同寬度；達不到需求的建議居中處理。
表格：
我談論一點：
- 表格的作用：對內容的分類和組織，能用表格表達比文字好。
其他：注意整體風格。
綜上：編寫文檔的兩個思維是：
- 流程化：1. 先有什么 2. 后有什么 3. 最后結果
- 精細化：邏輯表達、內容組織、排版
