个人中心
gpt4 book ai didi

技术文档书写规范指南

转载 作者：撒哈拉 更新时间：2024-12-06 08:23:25 57 4
gpt4 key购买 nike

文档是技术产品的重要组成部分，撰写各类技术文档应成为研发人员的日常工作之一。对于个人而言，书写文档不仅有助于提高写作水平，还能在写作过程中重新梳理产品架构，查缺补漏。对于团队来说，文档有助于知识共享和传递，提高开发与协作效率，保证项目后期的可维护性。文档是产品与用户之间的桥梁，是用户了解、学习和使用产品的关键媒介，有助于提升产品力和用户信心。建议研发人员在产品研发过程中，重视文档的积累和输出，以保证产品的长期、健康和可持续发展.

本指南仅包含约束技术文档的基本要求，以尽可能地确保文档语言和风格的一致性.

1、基本要求

1. 内容

语言表达清晰流畅，内容全面且成体系.

2. 格式

建议原始文档用 Markdown 格式书写并存档，使文档不依赖特定展示平台，便于传播及分享.

3. 组成部分

一个项目中的技术文档至少包含以下两类:

（1）用户手册：向用户介绍产品及其使用方法，以帮助用户快速了解产品功能并掌握使用方法.

（2）技术手册：提供详细的技术信息，如技术选型、设计方案、使用规范、测试报告、部署配置等文档，既能规范开发过程、支持团队协作，也能帮助用户更好地理解和使用产品.

此外建议添加项目文档，用于记录项目执行过程中相关资料，如项目计划、会议纪要等.

4. 文档体系

可参考如下文档体系结构:

├── 简介（Introduction）：[必备] 提供对产品和文档本身的总体的、扼要的说明
├── 快速上手（Getting Started）：[可选] 如何最快速地使用产品
├── 入门篇（Basics）：[必备] 又称“使用篇”，提供初级的使用教程
│   ├── 环境准备（Prerequisite）：[必备] 软件使用需要满足的前置条件
│   ├── 安装（Installation）：[可选]  软件的安装方法
│   ├── 设置（Configuration）：[必备]  软件的设置
├── 进阶篇（Advanced)：[可选] 又称“开发篇”，提供中高级的开发教程
├── API（Reference）：[可选] 软件 API 的逐一介绍
├── FAQ：[可选]  常见问题解答

参考自 阮一峰 - 中文技术文档的写作规范 - 文档体系篇 。

借鉴案例：YApi 。

2、书写规范

以下内容主要参考自 阮一峰 - 中文技术文档的写作规范 。

1. 标题

建议最多只支持四级标题:

（1）一级标题：文章的标题，建议有且仅有一个 。

（2）二级标题：文章主要部分的大标题 。

（3 三级标题：二级标题下面一级的小标题 。

（4）四级标题：三级标题下面某一方面的小标题，谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节 。

示例:

# 文档名称

## 1、二级标题

### 1. 三级小标题

（1）序号1

（2）序号2

### 2. 三级小标题

## 2、二级标题

2. 文本

建议:

（1）避免使用长句.

（2）尽量使用简单句和并列句，避免使用复合句.

（3）同样一个意思，尽量使用肯定句表达，不使用否定句表达.

（4）避免使用双重否定句.

（5）尽量不使用被动语态，改为使用主动语态.

更多文本书写建议，请查阅 阮一峰 - 中文技术文档的写作规范 - 文本篇 。

3. 段落

建议:

（1）一个段落只能有一个主题，或一个中心句子.

（2）段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为中心句子服务.

（3）段落之间使用一个空行隔开.

（4）段落开头不要留出空白字符.

4. 数值

建议:

（1）阿拉伯数字一律使用半角形式，不得使用全角形式.

（2）数值为千位以上，应添加千分号（半角逗号）.

5. 标点符号

建议:

（1）中文语句的标点符号，均应该采取全角符号，这样可以与全角文字保持视觉的一致.

（2）如果整句为英文，则该句使用英文/半角标点.

（3）句号、问号、叹号、逗号、顿号、分号和冒号不得出现在一行之首.

（4）点号（句号、逗号、顿号、分号、冒号）不得出现在标题的末尾，而标号（引号、括号、破折号、省略号、书名号、着重号、间隔号、叹号、问号）可以.

3、推荐工具

建议使用 VSCode 编写 Markdown.

1. VSCode

如果您使用 VSCode 书写 Markdown，建议安装以下插件以提高书写效率，并使之符合开发者中心格式规范.

（1）Paste Image 。

支持将图片粘贴至 md 文件中，并把图片文件统一保存到 md 文件同级的 img 目录下.

（2）Markdown All in One 。

支持各类快捷键、默认配置、表格格式化及预览等.

（3）markdownlint 。

规范 Markdown 文档格式，确保团队格式一致，且完美兼容开发者中心格式要求.

建议配置:

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

（4）AutoCorrect 。

用于「自动纠正」或「检查并建议」文案，给 CJK（中文、日语、韩语）与英文混写的场景，补充正确的空格，同时尝试以安全的方式自动纠正标点符号等等.

2. LLM (GPT)

LLM 在文档书写过程中，可承担修改错字、文档润色等功能，以提高文档输出质量，以下案例仅供参考:

（1）更正 。

角色提示词设置参考如下:

你既是语文老师，又是内容安全审核专家，请根据我输入的内容，判断其是否存在以下问题：

1. 错别字。
2. 语义明显不通顺。
3. 包含敏感信息，如用户名、密码、网络 IP、银行卡账号等。

若存在上述问题请单独指出，无需输出修改后的内容。

（2）润色 。

你是一个专业的文章润色师，请修改和润色我输入的内容，确保输出内容语言流畅、逻辑清晰、格式正确和表达效果好。

4、引文

阮一峰 - 中文技术文档的写作规范 。

MDN - 文档书写规范 。

Google Developer Documentation Style Guide 。

最后此篇关于技术文档书写规范指南的文章就讲到这里了,如果你想了解更多关于技术文档书写规范指南的内容请搜索CFSDN的文章或继续浏览相关文章，希望大家以后支持我的博客！ 。

57 4 0
文章推荐： a标签与Blob下载文件的区别和获取文件下载进度
文章推荐： Astrov5xDevNow
文章推荐： 使用SemanticKernel对接Ollma
文章推荐： 开源-Ideal库-Excel帮助类，ExcelHelper实现（五）
撒哈拉
个人简介

我是一名优秀的程序员,十分优秀！

滴滴打车优惠券免费领取
滴滴打车优惠券
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com