欧美成人精品手机在线观看_69视频国产_动漫精品第一页_日韩中文字幕网 - 日本欧美一区二区

文檔是技術(shù)產(chǎn)品的重要組成部分，撰寫各類技術(shù)文檔應(yīng)成為研發(fā)人員的日常工作之一。對(duì)于個(gè)人而言，書寫文檔不僅有助于提高寫作水平，還能在寫作過(guò)程中重新梳理產(chǎn)品架構(gòu)，查缺補(bǔ)漏。對(duì)于團(tuán)隊(duì)來(lái)說(shuō)，文檔有助于知識(shí)共享和傳遞，提高開(kāi)發(fā)與協(xié)作效率，保證項(xiàng)目后期的可維護(hù)性。文檔是產(chǎn)品與用戶之間的橋梁，是用戶了解、學(xué)習(xí)和使用產(chǎn)品的關(guān)鍵媒介，有助于提升產(chǎn)品力和用戶信心。建議研發(fā)人員在產(chǎn)品研發(fā)過(guò)程中，重視文檔的積累和輸出，以保證產(chǎn)品的長(zhǎng)期、健康和可持續(xù)發(fā)展。

本指南僅包含約束技術(shù)文檔的基本要求，以盡可能地確保文檔語(yǔ)言和風(fēng)格的一致性。

一、基本要求

1. 內(nèi)容

語(yǔ)言表達(dá)清晰流暢，內(nèi)容全面且成體系。

2. 格式

建議原始文檔用 Markdown 格式書寫并存檔，使文檔不依賴特定展示平臺(tái)，便于傳播及分享。

3. 存放位置

建議保存在項(xiàng)目 doc 文件夾下。

4. 組成部分

一個(gè)技術(shù)項(xiàng)目至少包含 README.md 文件、兩類必要文檔和兩類可選文檔。

（1）README.md：用于項(xiàng)目簡(jiǎn)介及各類文檔的入口說(shuō)明。

（2）項(xiàng)目文檔：用于記錄項(xiàng)目執(zhí)行過(guò)程中相關(guān)資料，如項(xiàng)目計(jì)劃、會(huì)議紀(jì)要等。

（3）技術(shù)手冊(cè)：提供詳細(xì)的技術(shù)信息，如技術(shù)選型、設(shè)計(jì)方案、使用規(guī)范、測(cè)試報(bào)告、部署配置等文檔，既能規(guī)范開(kāi)發(fā)過(guò)程、支持團(tuán)隊(duì)協(xié)作，也能幫助用戶更好地理解和使用產(chǎn)品。

（4）用戶手冊(cè)：如果該項(xiàng)目是面向非專業(yè)的普通用戶，應(yīng)向用戶介紹產(chǎn)品及其使用方法，以幫助用戶快速了解產(chǎn)品功能并掌握使用方法。

（5）接口文檔：如果該項(xiàng)目是后端服務(wù)，應(yīng)包含接口文檔，用于維護(hù)對(duì)外接口說(shuō)明，以便于團(tuán)隊(duì)內(nèi)部溝通和跨團(tuán)隊(duì)合作，建議將其保存到類似 YAPI 的專用接口文檔管理平臺(tái)，該平臺(tái)支持項(xiàng)目管理、在線調(diào)用、Mock 等必要功能。

整體組成如下：

├── doc
│   ├── 項(xiàng)目文檔：[必要] 
│   ├── 技術(shù)手冊(cè)：[必要] 
│   ├── 用戶手冊(cè)：[可選] 
│   ├── 接口文檔：[可選] 
├── README.md：[必要] 

5. 文檔體系

（1）項(xiàng)目文檔

├── 需求管理：純技術(shù)項(xiàng)目，如果使用 gitlab 管理源碼，可以將需求維護(hù)到 issue 上
├── 項(xiàng)目計(jì)劃
│   ├── 周
│   ├── 月
│   ├── 季
│   ├── 年
├── 會(huì)議紀(jì)要
├── 等

（2）技術(shù)手冊(cè)

├── 技術(shù)選型
├── 設(shè)計(jì)方案
├── 使用規(guī)范
├── 部署配置
├── 測(cè)試報(bào)告
├── 問(wèn)題定位

（3）用戶手冊(cè)

可參考如下文檔體系結(jié)構(gòu)：

├── 簡(jiǎn)介（Introduction）：[必要] 提供對(duì)產(chǎn)品和文檔本身的總體的、扼要的說(shuō)明
├── 快速上手（Getting Started）：[可選] 如何最快速地使用產(chǎn)品
├── 入門篇（Basics）：[必要] 又稱“使用篇”，提供初級(jí)的使用教程
│   ├── 環(huán)境準(zhǔn)備（Prerequisite）：[必要] 軟件使用需要滿足的前置條件
│   ├── 安裝（Installation）：[可選]  軟件的安裝方法
│   ├── 設(shè)置（Configuration）：[必要]  軟件的設(shè)置
├── 進(jìn)階篇（Advanced)：[可選] 又稱“開(kāi)發(fā)篇”，提供中高級(jí)的開(kāi)發(fā)教程
├── API（Reference）：[可選] 軟件 API 的逐一介紹
├── FAQ：[可選]  常見(jiàn)問(wèn)題解答

參考自 阮一峰 - 中文技術(shù)文檔的寫作規(guī)范 - 文檔體系篇

借鑒案例：YApi

二、書寫規(guī)范

以下內(nèi)容主要參考自 阮一峰 - 中文技術(shù)文檔的寫作規(guī)范

1. 標(biāo)題

建議最多只支持四級(jí)標(biāo)題：

（1）一級(jí)標(biāo)題：文章的標(biāo)題，建議有且僅有一個(gè)

（2）二級(jí)標(biāo)題：文章主要部分的大標(biāo)題

（3 三級(jí)標(biāo)題：二級(jí)標(biāo)題下面一級(jí)的小標(biāo)題

（4）四級(jí)標(biāo)題：三級(jí)標(biāo)題下面某一方面的小標(biāo)題，謹(jǐn)慎使用四級(jí)標(biāo)題，盡量避免出現(xiàn)，保持層級(jí)的簡(jiǎn)單，防止出現(xiàn)過(guò)于復(fù)雜的章節(jié)

示例：

# 文檔名稱
## 一、二級(jí)標(biāo)題
### 1. 三級(jí)小標(biāo)題
（1）序號(hào)1
（2）序號(hào)2
### 2. 三級(jí)小標(biāo)題
## 二、二級(jí)標(biāo)題

2. 文本

建議：

（1）避免使用長(zhǎng)句。

（2）盡量使用簡(jiǎn)單句和并列句，避免使用復(fù)合句。

（3）同樣一個(gè)意思，盡量使用肯定句表達(dá)，不使用否定句表達(dá)。

（4）避免使用雙重否定句。

（5）盡量不使用被動(dòng)語(yǔ)態(tài)，改為使用主動(dòng)語(yǔ)態(tài)。

更多文本書寫建議，請(qǐng)查閱 阮一峰 - 中文技術(shù)文檔的寫作規(guī)范 - 文本篇

3. 段落

建議：

（1）一個(gè)段落只能有一個(gè)主題，或一個(gè)中心句子。

（2）段落的中心句子放在段首，對(duì)全段內(nèi)容進(jìn)行概述。后面陳述的句子為中心句子服務(wù)。

（3）段落之間使用一個(gè)空行隔開(kāi)。

（4）段落開(kāi)頭不要留出空白字符。

4. 數(shù)值

建議：

（1）阿拉伯?dāng)?shù)字一律使用半角形式，不得使用全角形式。

（2）數(shù)值為千位以上，應(yīng)添加千分號(hào)（半角逗號(hào)）。

5. 標(biāo)點(diǎn)符號(hào)

建議：

（1）中文語(yǔ)句的標(biāo)點(diǎn)符號(hào)，均應(yīng)該采取全角符號(hào)，這樣可以與全角文字保持視覺(jué)的一致。

（2）如果整句為英文，則該句使用英文/半角標(biāo)點(diǎn)。

（3）句號(hào)、問(wèn)號(hào)、嘆號(hào)、逗號(hào)、頓號(hào)、分號(hào)和冒號(hào)不得出現(xiàn)在一行之首。

（4）點(diǎn)號(hào)（句號(hào)、逗號(hào)、頓號(hào)、分號(hào)、冒號(hào)）不得出現(xiàn)在標(biāo)題的末尾，而標(biāo)號(hào)（引號(hào)、括號(hào)、破折號(hào)、省略號(hào)、書名號(hào)、著重號(hào)、間隔號(hào)、嘆號(hào)、問(wèn)號(hào)）可以。

三、推薦工具

建議使用 VSCode 編寫 Markdown。

1. VSCode

如果您使用 VSCode 書寫 Markdown，建議安裝以下插件以提高書寫效率，并使之符合開(kāi)發(fā)者中心格式規(guī)范。

（1）Paste Image

支持將圖片粘貼至 md 文件中，并把圖片文件統(tǒng)一保存到 md 文件同級(jí)的 img 目錄下。

（2）Markdown All in One

支持各類快捷鍵、默認(rèn)配置、表格格式化及預(yù)覽等。

（3）markdownlint

規(guī)范 Markdown 文檔格式，確保團(tuán)隊(duì)格式一致，且完美兼容開(kāi)發(fā)者中心格式要求。

建議配置：

"markdownlint.config": {
    "MD024":false,
    "MD047":false,
    "MD034": false,
    "MD033": false,
}

（4）AutoCorrect

用于「自動(dòng)糾正」或「檢查并建議」文案，給 CJK（中文、日語(yǔ)、韓語(yǔ)）與英文混寫的場(chǎng)景，補(bǔ)充正確的空格，同時(shí)嘗試以安全的方式自動(dòng)糾正標(biāo)點(diǎn)符號(hào)等等。

2. LLM (GPT)

LLM 在文檔書寫過(guò)程中，可承擔(dān)修改錯(cuò)字、文檔潤(rùn)色等功能，以提高文檔輸出質(zhì)量，以下案例僅供參考：

（1）更正

角色提示詞設(shè)置參考如下：

你既是語(yǔ)文老師，又是內(nèi)容安全審核專家，請(qǐng)根據(jù)我輸入的內(nèi)容，判斷其是否存在以下問(wèn)題：
1. 錯(cuò)別字。
2. 語(yǔ)義明顯不通順。
3. 包含敏感信息，如用戶名、密碼、網(wǎng)絡(luò) IP、銀行卡賬號(hào)等。
若存在上述問(wèn)題請(qǐng)單獨(dú)指出，無(wú)需輸出修改后的內(nèi)容。

（2）潤(rùn)色

你是一個(gè)專業(yè)的文章潤(rùn)色師，請(qǐng)修改和潤(rùn)色我輸入的內(nèi)容，確保輸出內(nèi)容語(yǔ)言流暢、邏輯清晰、格式正確和表達(dá)效果好。

四、引文

阮一峰 - 中文技術(shù)文檔的寫作規(guī)范

MDN - 文檔書寫規(guī)范

Google Developer Documentation Style Guide

?轉(zhuǎn)自https://www.cnblogs.com/zengzuo613/p/18589348