1.背景    

接手新項目或者階段性切換項目開發再或者翻閱社區項目時，快速run起來的技能方式通常是閱讀項目下的名為 README.md文檔所得。

前面所述僅僅是萬里長征的第一步，當你想了解項目所使用的技術棧、組件庫、工具庫等等一些開發所需物料時，翻閱依賴管理文件的三方包或者業務代碼模塊時，往往結果也是比較懵圈的，一個穩定運行的項目倉庫伴隨著業務的增長以及技術的更新升級換代，有可能其中包含多種相似物料庫，如 element ui、antd-vue、自研組件庫等并存情況下，如何取舍與避坑是未知的。

依據需求開發時項目中所包含的目錄結構是如何劃分的，當前業務模塊應當存放的目錄該不該隨意存放；開發中所用到的工具在現有的工具箱內是否具備，新增加會不會存在重復造輪子；該業務板塊的相關負責人如何查找，各個環境的訪問的域名是哪個，開發提測發布應用名叫什么，接口權限或菜單的配置又是哪個系統，登錄該系統一直提示尚無權限找誰開通等等這些，不勝枚舉的阻力相信各位讀者都是過來人，皆可產生共鳴。

2.收益    

降低初次項目 run 起時遇到問題的幾率，各種權限申請、各個環境下的系統地址訪問、功能開發目錄存放、項目所需物料的詢問、查詢、溝通與聯調時代理配置的成本；

提升需求專注度，將精力用在需求解讀與實現，利用一份避坑指南；

提升可維護性：保持開發環境配置一致性。

3.內容    

旨在幫助業務項目文檔書寫指導：

3.1 項目名稱

項目名稱作為我們認識新項目的首要關注點，對于一些項目倉庫的創建時常遇到只有幾個字母之差，但業務完全不關聯或非需求涉及的項目，這對于一個新手會造成誤解，因此名稱也更能明確我們在眾多倉庫搜索目標庫的一個較重要的參考。

3.2 開發環境

(1) 運行準備

由于一些新老業務項目并存情況及nodejs@version版本更新發布之快，運行不同項目常常出現因默認使用版本差異，導致切換項目運行后控制臺報錯。

依H5前端項目來講、從Git 倉庫 down 下拉后，潛意識中是執行依賴包安裝 npm或者yarn因為那是運行項目的必要前提；因此需注明當前項目所使用的包管理工具類型，避免因慣性思維采用不匹配的管理工具耗費過長時間后驚奇的發現用錯了，此時的心情便是這世間最讓人抓狂的等待，消磨人性的暗黑時刻。

H5前端目前主流及為人所知的分別是 React、Vue、Angular等，必要的技術棧說明能給人一種實現功能思路切換的時間，因為這里面牽涉到UI組件庫選型是 Antd-*、 Element-ui 或者其他主流組件庫，在開發需求時也能夠為開發前明確是否需要花費時間來做些技術儲備、需求是否需評估額外時間。

通常C端產品是不需要進行菜單&接口路由配置，但對于B端系統，往往需進行菜單配置，為了能夠準確無誤的將所完成的功能進行提測以及發布生產，大多數情況下是需要自己進行菜單、接口路由配置，但新手如何才能快速的了解配置渠道及需配置系統權限的申請，最好可以給配置文檔直達鏈接，遇到權限、配置問題時，明確可尋求支持同學，降低對新手所帶來的損傷。

為了保證代碼風格統一、提前告知開發當前項目需執行哪些配置、關閉IDE什么插件等，避免出現使用IDE 格式化插件與項目 ESLint 風格沖突，導致運行時出現一堆讓人抓狂的爆紅提示。

（2）項目啟動

針對于需通過 SSO 權限身份驗證的場景，大多數是通過驗證根域名的合法性進行授權，此種情形需在本地 hosts 文件綁定 localhost 到指定域名下，以便在開發時正常獲取驗證身份。通常是通過 yarn dev / npm run dev 方式進行默認的本地開發，但不同業務系統所要求存在差異，因需配合后端以及不同項目的要求有所區分，明確的說明可降低啟動時的多環境重試或詢問的成本。

對于一個新項目或新業務，再需求prd 或評審時講到參照哪哪模塊，對于此時的新手是盲目的，不知該如何查看該模塊現狀是，因此對于產品的直達鏈接顯得尤為重要，因為這是一個可快速訪問的入口。

大多數情況下開發時都多多少少的因環境不穩定、環境被緊急占用或涉及到其他域的訪問，是有必要進行接口代理配置的，一個清晰明了便捷的配置姿勢以及目錄顯得格外的迫切。

(3)目錄劃分

展現形式：Markdown 樹狀結構，借助工具 tree 生成。

對于項目業務模塊的劃分說明也是不可或缺的重要組成部分，因為當要進行相應的業務模塊功能開發時，是需要知道是該相關模塊否存在、以及存放的位置，可使得后人快速定位；對對應模塊進行相應操作或迭代。

基于不斷的版本升級迭代，符合具體業務的場景的公共部分被逐漸的抽離，作為項目的公共資源 e.g. 各種組件、工具庫、網絡庫等部分，明確的標注避免新手重復造輪子。

(4)SDK文檔

對于一些非社區主流資源的引入，比如組內或小眾的二方、三方資源的采用，建議給文檔進行貼入文檔內，以便開發或排查問題時能夠快速的去翻閱文檔，避免在一些非科學上網的情況下出現無跡可尋。

(5)避坑指南

大多數人較少經歷開發時皆為全新架構、版本的新啟動項目，因此對于所涉及的項目所采用的資源包存在歷史原因等特殊場景，期間解決問題的思路、踩過的坑等寶貴的歷程與經驗的記錄，能幫助后人避免類似的情況發生；

(6)項目部署

持續集成比較重要的一環是將功能進行部署，而此時懷揣著激動的小手準備發布時，發現不知是那扇門，所以一個清晰明了的應用名與直達發布系統的鏈接顯得讓人格外的期待。

(7)監控告警

軟件工程發展至今已進入打磨階段，一個軟件產品還處于裸奔的時代已基本一去不復返，因此對于在測試驗收時的有限場景下問題修復完畢的情況下，便是進行生產真實用戶場景下運行健康狀態的觀察、此時可明確該項目已接入的監控；

3.3 業務介紹

業務域：清楚講述項目所屬業務域、幫助快速樹立業務印象，結合該業務下各版本功能說明文檔，將有助開發同學對于業務的背后的業務價值有初步的理解；

迭代方式：依據不同的業務采用的需求迭代方式存在一些差異，有項目制的、敏捷開發方式，對于不同的迭代方式所采用的節奏也有所不同；推動項目落實的方式有產品驅動或PMO方式，目前大多數為后者，在得物采用更為高效的系統RDC，其具備從MRD、PRD、評審、排期、任務分配、風險把控、人力資源等等精細化運作方式，將需求落地以流水線式的完成及把控等能力；

相關人員：將項目所涉及人員進行維護在項目內、不定時更新，在有需求或排查問題時能夠幫助快速找到相關同學進行支持，至少大多數時也能讓你幫你找到對應功能點當時有參與或了解的同學，提升溝通效率等好處。

4.總結    

項目文檔是對于項目一個快速了解的一個最好方式，能從中獲取到其是所服務的業務，參與開發所具備的知識體系，開發前所需做哪些準備，遇到問題時能聯系到對應的同學，不僅能幫助新手快速上手，同時也有助于多個項目并行時，相互之間進行切換起到溫故的效果；總之一個優秀項目文檔不僅僅要讓團隊組員看得懂、用得順手，也需要讓其他成員看得懂、做得出才方可發揮其潛在價值。