Laravel 項(xiàng)目開發(fā)規(guī)范 項(xiàng)目文檔編寫規(guī)范

說明

每一個(gè)項(xiàng)目都 必須 包含一個(gè) readme.md 文件，readme 里書寫這個(gè)項(xiàng)目的簡單信息。作用主要有兩個(gè)，一個(gè)是團(tuán)隊(duì)新成員可從此文件中快速獲悉項(xiàng)目大致情況，另一個(gè)是部署項(xiàng)目時(shí)可以作為參考。

1. 排版規(guī)范

文檔頁面排版 必須 遵循 中文文案排版指北 ，在此基礎(chǔ)上：

• 中文文檔請使用全角標(biāo)點(diǎn)符號(hào)；
• 必須 遵循 Markdown 語法，勿讓代碼顯示錯(cuò)亂；
• 原文中的雙引號(hào)（” “）請代換成中文的引號(hào)（『』符號(hào)怎么打出來見 這里）。
• 所有的 「加亮」、「加粗」和「鏈接」都需要在左右保持一個(gè)空格。

2. 行文規(guī)范

readme.md 文檔 應(yīng)該 包含以下內(nèi)容：

• 「項(xiàng)目概述」- 介紹說明項(xiàng)目的一些情況，類似于簡單的產(chǎn)品說明，簡單的功能描述，項(xiàng)目相關(guān)鏈接等，500 字以內(nèi)；
• 「運(yùn)行環(huán)境」- 運(yùn)行環(huán)境說明，系統(tǒng)要求等信息；
• 「開發(fā)環(huán)境部署 / 安裝」- 一步一步引導(dǎo)說明，保證項(xiàng)目新成員能最快速的，沒有歧義的部署好開發(fā)環(huán)境；
• 「服務(wù)器架構(gòu)說明」- 最好能有服務(wù)器架構(gòu)圖，從用戶瀏覽器請求開始，包括后端緩存服務(wù)使用等都描述清楚（主要體現(xiàn)為軟件的使用），配合「運(yùn)行環(huán)境」區(qū)塊內(nèi)容，可作為線上環(huán)境部署的依據(jù)；
• 「代碼上線」- 介紹代碼上線流程，需要執(zhí)行哪些步驟；
• 「擴(kuò)展包說明」- 表格列出所有使用的擴(kuò)展包，還有在哪些業(yè)務(wù)邏輯或者用例中使用了此擴(kuò)展包；
• 「自定義 Artisan 命令列表」- 以表格形式羅列出所有自定義的命令，說明用途，指出調(diào)用場景；
• 「隊(duì)列列表」- 以表格形式羅列出項(xiàng)目所有隊(duì)列接口，說明用途，指出調(diào)用場景。