大綱
- 回顧 17 年，文檔寫作泛濫、深度不足
- 重申文檔寫作的必要性
- 文檔標題格式
- 文檔迭代更新
- 文檔上線
回顧 17 年嘉抒，文檔寫作泛濫、深度不足
文檔泛濫體現(xiàn)在：同一主題創(chuàng)建多個文檔袍暴、同一題目創(chuàng)建多個文檔些侍、甚至同一內(nèi)容補充更新時也創(chuàng)建了多個文檔隶症，經(jīng)常出現(xiàn)的現(xiàn)象就是一個功能點每個人都只寫了自己所涉及到的一方面，項目文件夾內(nèi)的文檔太多反而不方便查詢信息岗宣。
單方面的思考為什么會出現(xiàn)這類情況：
- 不理解項目文件更深層的協(xié)作意義蚂会，只是作為自己的記事本在用
- 被點名整理文檔，為了工作而工作
- 文檔寫作沒有規(guī)范耗式，大家無所遵從
文檔寫作深度不足體現(xiàn)在：不理解 markdown 存在的意義胁住，筆記中會出現(xiàn)各種顏色、種類的字體刊咳；甚至基本的 markdown 語法錯誤隨處可見措嵌；文檔主題表達的完整性；迭代更新的后續(xù)動力芦缰。
markdown 是純文本寫作企巢，拷貝內(nèi)容至印象筆記中時請忽略樣式，ctl/command + shift + v, 需要樣式時請使用 markdown 語法表達让蕾。
重申文檔寫作的必要性
- 需求文檔方便同事間協(xié)作交流浪规，避免重復解釋或信息傳輸錯誤
- 功能文檔增強開發(fā)同事的思考，圖文描述不清的功能無法驗收
- 項目文檔梳理各個服務的配置探孝，避免手工操作時失誤
- 部署文檔記錄各個服務的部署笋婿，避免后續(xù)運維的失憶
- 說明文檔自定義主題，根據(jù)實際需求解釋內(nèi)容
- 培訓文檔講解知識點顿颅，共享知識助力團隊建設
所有文檔共同具有的特性：
- 單一性：寫作一次缸濒，被 N 個人詢問只需要共享 N 次
- 跌代性：主題表述有誤、信息過期需要更新粱腻，只需要更新文檔內(nèi)容即可庇配，一次性共享給關聯(lián)的所有同事
- 確定性：遇事不靠記憶，找到對應文檔绍些，白底黑字捞慌，不存在不確定的信息；必要時及時更新文檔
- 交付性：完成了功能開發(fā)柬批，還需要交付部署信息啸澡、配置信息、功能說明文檔氮帐，而這些只需要把開發(fā)過程中的文檔整理出來即可
文檔標題格式
統(tǒng)一文檔標題格式：主題名稱 - 文檔標題
已經(jīng)在使用的主題名稱：
- 需求文檔
- 數(shù)據(jù)文檔
- 技術文檔
- 開發(fā)文檔
- 項目文檔
- 部署文檔
- 說明文檔
- 培訓文檔
可以根據(jù)需要自定義主題名稱嗅虏，符合標題格式即可。有更佳的標題格式歡迎交流討論上沐。
文檔迭代更新
文檔之所以會泛濫皮服，就是不懂得迭代更新文檔。
做好迭代更新就要堅持對主題名稱及文檔主旨，相同的主題及主旨已存在冰更，自然就應該去更新已存在的文檔产徊；
什么時候去更新已存在的文檔昂勒，什么時候去創(chuàng)建新的主題文檔蜀细，這個火候沒有明確定義，可以清晰的表述出自己的理解就可以戈盈。
盲目奠衔、隨意的創(chuàng)建文檔要點名批評，希望新的一年塘娶，文檔數(shù)量不用太多归斤，多關注內(nèi)容深度。
文檔上線
功能穩(wěn)定后刁岸，技術文檔脏里、培訓文檔主題表述清晰，有助于客戶虹曙、新同事理解產(chǎn)品的特性迫横，都會吸納到在線 gitbook 中；
文檔的數(shù)量與質量已經(jīng)成為考核團隊成員的評判依據(jù)之一酝碳，避免性格內(nèi)向的同事被忽略或低估了他們的工作成果矾踱。
