1.背景    

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

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

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

2.收益    

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

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

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

3.內(nèi)容    

旨在幫助業(yè)務(wù)項(xiàng)目文檔書寫指導(dǎo)：

3.1 項(xiàng)目名稱

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

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

(1) 運(yùn)行準(zhǔn)備

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

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

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

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

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

（2）項(xiàng)目啟動

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

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

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

(3)目錄劃分

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

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

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

(4)SDK文檔

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

(5)避坑指南

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

(6)項(xiàng)目部署

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

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

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

3.3 業(yè)務(wù)介紹

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

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

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

4.總結(jié)    

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