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

說明

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

1. 排版規(guī)范

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

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

2. 行文規(guī)范

readme.md 文檔 應該 包含以下內容：

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