建站
咨詢
售后
建站咨詢
新聞中心
1.背景
公司主營業(yè)務(wù)：網(wǎng)站設(shè)計制作、成都做網(wǎng)站、移動網(wǎng)站開發(fā)等業(yè)務(wù)。幫助企業(yè)客戶真正實現(xiàn)互聯(lián)網(wǎng)宣傳，提高企業(yè)的競爭能力。成都創(chuàng)新互聯(lián)公司是一支青春激揚、勤奮敬業(yè)、活力青春激揚、勤奮敬業(yè)、活力澎湃、和諧高效的團隊。公司秉承以“開放、自由、嚴(yán)謹、自律”為核心的企業(yè)文化，感謝他們對我們的高要求，感謝他們從不同領(lǐng)域給我們帶來的挑戰(zhàn)，讓我們激情的團隊有機會用頭腦與智慧不斷的給客戶帶來驚喜。成都創(chuàng)新互聯(lián)公司推出甘孜州免費做網(wǎng)站回饋大家。
接手新項目或者階段性切換項目開發(fā)再或者翻閱社區(qū)項目時，快速run起來的技能方式通常是閱讀項目下的名為 README.md文檔所得。
前面所述僅僅是萬里長征的第一步，當(dāng)你想了解項目所使用的技術(shù)棧、組件庫、工具庫等等一些開發(fā)所需物料時，翻閱依賴管理文件的三方包或者業(yè)務(wù)代碼模塊時，往往結(jié)果也是比較懵圈的，一個穩(wěn)定運行的項目倉庫伴隨著業(yè)務(wù)的增長以及技術(shù)的更新升級換代，有可能其中包含多種相似物料庫，如 element ui、antd-vue、自研組件庫等并存情況下，如何取舍與避坑是未知的。
依據(jù)需求開發(fā)時項目中所包含的目錄結(jié)構(gòu)是如何劃分的，當(dāng)前業(yè)務(wù)模塊應(yīng)當(dāng)存放的目錄該不該隨意存放；開發(fā)中所用到的工具在現(xiàn)有的工具箱內(nèi)是否具備，新增加會不會存在重復(fù)造輪子；該業(yè)務(wù)板塊的相關(guān)負責(zé)人如何查找，各個環(huán)境的訪問的域名是哪個，開發(fā)提測發(fā)布應(yīng)用名叫什么，接口權(quán)限或菜單的配置又是哪個系統(tǒng)，登錄該系統(tǒng)一直提示尚無權(quán)限找誰開通等等這些，不勝枚舉的阻力相信各位讀者都是過來人，皆可產(chǎn)生共鳴。
2.收益
降低初次項目 run 起時遇到問題的幾率，各種權(quán)限申請、各個環(huán)境下的系統(tǒng)地址訪問、功能開發(fā)目錄存放、項目所需物料的詢問、查詢、溝通與聯(lián)調(diào)時代理配置的成本；
提升需求專注度，將精力用在需求解讀與實現(xiàn)，利用一份避坑指南；
提升可維護性：保持開發(fā)環(huán)境配置一致性。
3.內(nèi)容
旨在幫助業(yè)務(wù)項目文檔書寫指導(dǎo)：
3.1 項目名稱
項目名稱作為我們認識新項目的首要關(guān)注點，對于一些項目倉庫的創(chuàng)建時常遇到只有幾個字母之差，但業(yè)務(wù)完全不關(guān)聯(lián)或非需求涉及的項目，這對于一個新手會造成誤解，因此名稱也更能明確我們在眾多倉庫搜索目標(biāo)庫的一個較重要的參考。
3.2 開發(fā)環(huán)境
(1) 運行準(zhǔn)備
由于一些新老業(yè)務(wù)項目并存情況及nodejs@version版本更新發(fā)布之快，運行不同項目常常出現(xiàn)因默認使用版本差異，導(dǎo)致切換項目運行后控制臺報錯。
依H5前端項目來講、從Git 倉庫 down 下拉后，潛意識中是執(zhí)行依賴包安裝 npm或者yarn因為那是運行項目的必要前提；因此需注明當(dāng)前項目所使用的包管理工具類型，避免因慣性思維采用不匹配的管理工具耗費過長時間后驚奇的發(fā)現(xiàn)用錯了，此時的心情便是這世間最讓人抓狂的等待，消磨人性的暗黑時刻。
H5前端目前主流及為人所知的分別是 React、Vue、Angular等，必要的技術(shù)棧說明能給人一種實現(xiàn)功能思路切換的時間，因為這里面牽涉到UI組件庫選型是 Antd-*、 Element-ui 或者其他主流組件庫，在開發(fā)需求時也能夠為開發(fā)前明確是否需要花費時間來做些技術(shù)儲備、需求是否需評估額外時間。
通常C端產(chǎn)品是不需要進行菜單&接口路由配置，但對于B端系統(tǒng)，往往需進行菜單配置，為了能夠準(zhǔn)確無誤的將所完成的功能進行提測以及發(fā)布生產(chǎn)，大多數(shù)情況下是需要自己進行菜單、接口路由配置，但新手如何才能快速的了解配置渠道及需配置系統(tǒng)權(quán)限的申請，最好可以給配置文檔直達鏈接，遇到權(quán)限、配置問題時，明確可尋求支持同學(xué)，降低對新手所帶來的損傷。
為了保證代碼風(fēng)格統(tǒng)一、提前告知開發(fā)當(dāng)前項目需執(zhí)行哪些配置、關(guān)閉IDE什么插件等，避免出現(xiàn)使用IDE 格式化插件與項目 ESLint 風(fēng)格沖突，導(dǎo)致運行時出現(xiàn)一堆讓人抓狂的爆紅提示。
（2）項目啟動
針對于需通過 SSO 權(quán)限身份驗證的場景，大多數(shù)是通過驗證根域名的合法性進行授權(quán)，此種情形需在本地 hosts 文件綁定 localhost 到指定域名下，以便在開發(fā)時正常獲取驗證身份。通常是通過 yarn dev / npm run dev 方式進行默認的本地開發(fā)，但不同業(yè)務(wù)系統(tǒng)所要求存在差異，因需配合后端以及不同項目的要求有所區(qū)分，明確的說明可降低啟動時的多環(huán)境重試或詢問的成本。
對于一個新項目或新業(yè)務(wù)，再需求prd 或評審時講到參照哪哪模塊，對于此時的新手是盲目的，不知該如何查看該模塊現(xiàn)狀是，因此對于產(chǎn)品的直達鏈接顯得尤為重要，因為這是一個可快速訪問的入口。
大多數(shù)情況下開發(fā)時都多多少少的因環(huán)境不穩(wěn)定、環(huán)境被緊急占用或涉及到其他域的訪問，是有必要進行接口代理配置的，一個清晰明了便捷的配置姿勢以及目錄顯得格外的迫切。
(3)目錄劃分
展現(xiàn)形式：Markdown 樹狀結(jié)構(gòu)，借助工具 tree 生成。
對于項目業(yè)務(wù)模塊的劃分說明也是不可或缺的重要組成部分，因為當(dāng)要進行相應(yīng)的業(yè)務(wù)模塊功能開發(fā)時，是需要知道是該相關(guān)模塊否存在、以及存放的位置，可使得后人快速定位；對對應(yīng)模塊進行相應(yīng)操作或迭代。
基于不斷的版本升級迭代，符合具體業(yè)務(wù)的場景的公共部分被逐漸的抽離，作為項目的公共資源 e.g. 各種組件、工具庫、網(wǎng)絡(luò)庫等部分，明確的標(biāo)注避免新手重復(fù)造輪子。
(4)SDK文檔
對于一些非社區(qū)主流資源的引入，比如組內(nèi)或小眾的二方、三方資源的采用，建議給文檔進行貼入文檔內(nèi)，以便開發(fā)或排查問題時能夠快速的去翻閱文檔，避免在一些非科學(xué)上網(wǎng)的情況下出現(xiàn)無跡可尋。
(5)避坑指南
大多數(shù)人較少經(jīng)歷開發(fā)時皆為全新架構(gòu)、版本的新啟動項目，因此對于所涉及的項目所采用的資源包存在歷史原因等特殊場景，期間解決問題的思路、踩過的坑等寶貴的歷程與經(jīng)驗的記錄，能幫助后人避免類似的情況發(fā)生；
(6)項目部署
持續(xù)集成比較重要的一環(huán)是將功能進行部署，而此時懷揣著激動的小手準(zhǔn)備發(fā)布時，發(fā)現(xiàn)不知是那扇門，所以一個清晰明了的應(yīng)用名與直達發(fā)布系統(tǒng)的鏈接顯得讓人格外的期待。
(7)監(jiān)控告警
軟件工程發(fā)展至今已進入打磨階段，一個軟件產(chǎn)品還處于裸奔的時代已基本一去不復(fù)返，因此對于在測試驗收時的有限場景下問題修復(fù)完畢的情況下，便是進行生產(chǎn)真實用戶場景下運行健康狀態(tài)的觀察、此時可明確該項目已接入的監(jiān)控；
3.3 業(yè)務(wù)介紹
業(yè)務(wù)域：清楚講述項目所屬業(yè)務(wù)域、幫助快速樹立業(yè)務(wù)印象，結(jié)合該業(yè)務(wù)下各版本功能說明文檔，將有助開發(fā)同學(xué)對于業(yè)務(wù)的背后的業(yè)務(wù)價值有初步的理解；
迭代方式：依據(jù)不同的業(yè)務(wù)采用的需求迭代方式存在一些差異，有項目制的、敏捷開發(fā)方式，對于不同的迭代方式所采用的節(jié)奏也有所不同；推動項目落實的方式有產(chǎn)品驅(qū)動或PMO方式，目前大多數(shù)為后者，在得物采用更為高效的系統(tǒng)RDC，其具備從MRD、PRD、評審、排期、任務(wù)分配、風(fēng)險把控、人力資源等等精細化運作方式，將需求落地以流水線式的完成及把控等能力；
相關(guān)人員：將項目所涉及人員進行維護在項目內(nèi)、不定時更新，在有需求或排查問題時能夠幫助快速找到相關(guān)同學(xué)進行支持，至少大多數(shù)時也能讓你幫你找到對應(yīng)功能點當(dāng)時有參與或了解的同學(xué)，提升溝通效率等好處。
4.總結(jié)
項目文檔是對于項目一個快速了解的一個最好方式，能從中獲取到其是所服務(wù)的業(yè)務(wù)，參與開發(fā)所具備的知識體系，開發(fā)前所需做哪些準(zhǔn)備，遇到問題時能聯(lián)系到對應(yīng)的同學(xué)，不僅能幫助新手快速上手，同時也有助于多個項目并行時，相互之間進行切換起到溫故的效果；總之一個優(yōu)秀項目文檔不僅僅要讓團隊組員看得懂、用得順手，也需要讓其他成員看得懂、做得出才方可發(fā)揮其潛在價值。
網(wǎng)站名稱：一個滿分的項目文檔是如何書寫的
鏈接分享：http://www.dlmjj.cn/article/cdsssge.html
