1.背景    

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

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

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

2.收益    

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

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

提升可維護性：保持開發(fā)環(huán)境配置一致性。

3.內(nèi)容    

旨在幫助業(yè)務項目文檔書寫指導：

3.1 項目名稱

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

3.2 開發(fā)環(huán)境

(1) 運行準備

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

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

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

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

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

（2）項目啟動

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

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

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

(3)目錄劃分

展現(xiàn)形式：Markdown 樹狀結構，借助工具 tree 生成。

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

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

(4)SDK文檔

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

(5)避坑指南

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

(6)項目部署

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

(7)監(jiān)控告警

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

3.3 業(yè)務介紹

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

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

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

4.總結    

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