From 056639d9777b265a2a63137161874f52026ef103 Mon Sep 17 00:00:00 2001 From: 7Wate Date: Wed, 7 Aug 2024 16:20:43 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E9=87=8D=E6=9E=84?= =?UTF-8?q?=E5=AE=8C=E5=96=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../技术文档/{简介.md => 1.简介.md} | 52 ++++++++++++++++--- .../技术文档/{标点符号.md => 2.标点符号.md} | 13 +++-- .../技术文档/{命名约定.md => 3.命名约定.md} | 12 +++-- .../技术文档/{语言风格.md => 4.语言风格.md} | 12 +++-- .../技术文档/{文档内容.md => 5.文档内容.md} | 16 ++++-- .../技术文档/{文档结构.md => 6.文档结构.md} | 11 ++-- .../技术文档/{附录资料.md => 7.附录资料.md} | 2 +- .../谷歌开源项目风格指南.md | 17 ------ 8 files changed, 86 insertions(+), 49 deletions(-) rename Tech/software-engineering/技术文档/{简介.md => 1.简介.md} (60%) rename Tech/software-engineering/技术文档/{标点符号.md => 2.标点符号.md} (96%) rename Tech/software-engineering/技术文档/{命名约定.md => 3.命名约定.md} (93%) rename Tech/software-engineering/技术文档/{语言风格.md => 4.语言风格.md} (90%) rename Tech/software-engineering/技术文档/{文档内容.md => 5.文档内容.md} (97%) rename Tech/software-engineering/技术文档/{文档结构.md => 6.文档结构.md} (93%) rename Tech/software-engineering/技术文档/{附录资料.md => 7.附录资料.md} (99%) delete mode 100644 Tech/software-engineering/谷歌开源项目风格指南.md diff --git a/Tech/software-engineering/技术文档/简介.md b/Tech/software-engineering/技术文档/1.简介.md similarity index 60% rename from Tech/software-engineering/技术文档/简介.md rename to Tech/software-engineering/技术文档/1.简介.md index aaabdc82..93c2aae2 100644 --- a/Tech/software-engineering/技术文档/简介.md +++ b/Tech/software-engineering/技术文档/1.简介.md @@ -1,15 +1,19 @@ --- title: 简介 -description: 中文文档写作指南简介 +description: 本指南旨在规范中文技术文档的写作，提高可读性，统一风格，降低沟通成本。 keywords: - 中文 - 文档 - - 写作指南 + - 协作指南 + - 技术文档 + - 可读性 + - 统一风格 + - 沟通成本 tags: - 软件工程/技术文档 - 技术/软件工程 author: 7Wate -date: 2023-06-26 +date: 2024-08-07 --- ## 引言 @@ -28,15 +32,47 @@ date: 2023-06-26 - 审校文档过程中争议问题的裁决。 - 也可供软件界面、帮助文档等资料开发人员参考。 +## 目录大纲 + +### [简介](Tech/software-engineering/技术文档/1.简介.md) + +- 技术文档的重要性 +- 技术文档的类型 + +### [标点符号](Tech/software-engineering/技术文档/2.标点符号.md) + +- 标点符号的基本规则 +- 常见的错误用法 + +### [命名约定](Tech/software-engineering/技术文档/3.命名约定.md) + +- 命名约定的重要性 +- 常见的命名规则 + +### [语言风格](Tech/software-engineering/技术文档/4.语言风格.md) + +- 语言风格的定义 +- 一致性和简洁性的重要性 + +### [文档内容](Tech/software-engineering/技术文档/5.文档内容.md) + +- 文档内容的构成 +- 如何编写高质量的文档内容 + +### [文档结构](Tech/software-engineering/技术文档/6.文档结构.md) + +- 文档的基本结构 +- 不同类型文档的结构差异 + +### [附录资料](Tech/software-engineering/技术文档/7.附录资料.md) + +- 附录的定义 +- 附录的使用场景 + ## 使用原则 本指南是一本查询手册，建议初次阅读本指南时，先大致浏览目录章节结构，了解本指南涵盖的内容范围；之后就编写文档时碰到的实际问题，再回头查找相应规范。 -## 标点符号和格式排版 - -- **合理使用标点符号**：标点符号是语言的重要组成部分，合理地使用标点符号能够帮助读者更好地理解文档。 -- **格式统一**：保持文档的格式统一，例如字体、字号、行间距等。 - ## 修订和审查 1. **定期修订**：定期修订文档，以保持其准确性和时效性。 diff --git a/Tech/software-engineering/技术文档/标点符号.md b/Tech/software-engineering/技术文档/2.标点符号.md similarity index 96% rename from Tech/software-engineering/技术文档/标点符号.md rename to Tech/software-engineering/技术文档/2.标点符号.md index e8602f0f..91fcdba7 100644 --- a/Tech/software-engineering/技术文档/标点符号.md +++ b/Tech/software-engineering/技术文档/2.标点符号.md @@ -1,15 +1,18 @@ --- title: 标点符号 -description: 标点符号 +description: 本文详细介绍了中文标点符号的规范使用，包括句号、逗号、顿号等，并讨论了中英文混用时的标点规则。 keywords: - - 文档 - - 标点 - - 符号 + - 标点符号 + - 中文标点 + - 中英文混用 + - Markdown + - 引号 + - 括号 tags: - 软件工程/技术文档 - 技术/软件工程 author: 7Wate -date: 2023-06-26 +date: 2024-08-07 --- ## 常用中文标点符号 diff --git a/Tech/software-engineering/技术文档/命名约定.md b/Tech/software-engineering/技术文档/3.命名约定.md similarity index 93% rename from Tech/software-engineering/技术文档/命名约定.md rename to Tech/software-engineering/技术文档/3.命名约定.md index aacbf191..dc68b6e6 100644 --- a/Tech/software-engineering/技术文档/命名约定.md +++ b/Tech/software-engineering/技术文档/3.命名约定.md @@ -1,15 +1,17 @@ --- title: 命名约定 -description: 文档命名约定 +description: 本文规定了技术文档的文件命名规范，包括使用短划线、避免下划线、统一大小写和后缀，同时提出了产品命名和专用名称使用的标准化建议。 keywords: - - 文档 - - 命名 - - 约定 + - 文件命名 + - 产品命名 + - 名称使用 + - Markdown + - 技术文档 tags: - 软件工程/技术文档 - 技术/软件工程 author: 7Wate -date: 2023-06-26 +date: 2024-08-07 --- ## 文件命名 diff --git a/Tech/software-engineering/技术文档/语言风格.md b/Tech/software-engineering/技术文档/4.语言风格.md similarity index 90% rename from Tech/software-engineering/技术文档/语言风格.md rename to Tech/software-engineering/技术文档/4.语言风格.md index bc9ef375..27eb3806 100644 --- a/Tech/software-engineering/技术文档/语言风格.md +++ b/Tech/software-engineering/技术文档/4.语言风格.md @@ -1,15 +1,17 @@ --- title: 语言风格 -description: 语言风格 +description: 本文强调技术文档写作应采用对话式、客观礼貌的语气，追求简洁明了、通俗易懂的表达，以用户为导向，并确保用词恰当、统一，正确使用“的”、“地”、“得”，明确代词指代，以提高文档的易用性和清晰度。 keywords: - - 文档 - - 语言 - - 风格 + - 技术文档 + - 语言风格 + - 简洁明了 + - 通俗易懂 + - 用户导向 tags: - 软件工程/技术文档 - 技术/软件工程 author: 7Wate -date: 2023-06-26 +date: 2024-08-07 --- 在技术文档的写作中，风格和语气的掌握是至关重要的。下面是一些关于技术文档写作的基本准则。 diff --git a/Tech/software-engineering/技术文档/文档内容.md b/Tech/software-engineering/技术文档/5.文档内容.md similarity index 97% rename from Tech/software-engineering/技术文档/文档内容.md rename to Tech/software-engineering/技术文档/5.文档内容.md index 46115b48..c3696a7c 100644 --- a/Tech/software-engineering/技术文档/文档内容.md +++ b/Tech/software-engineering/技术文档/5.文档内容.md @@ -1,14 +1,22 @@ --- title: 文档内容 -description: 文档内容 +description: 本文提供了技术文档编写的详细规范，包括正确使用空白符号、列表、表格、图形图片、代码块及注释、链接和引用，以及缩略语和数字表达方式。强调了文档的清晰性、准确性和易读性，同时指出了常见的错误用法。 keywords: - - 文档 - - 内容 + - 技术文档 + - 协作规范 + - 空白符号 + - 列表 + - 表格 + - 图形 + - 代码 + - 链接 + - 缩略语 + - 数字 tags: - 软件工程/技术文档 - 技术/软件工程 author: 7Wate -date: 2023-06-26 +date: 2024-08-07 --- ## 空白符号 diff --git a/Tech/software-engineering/技术文档/文档结构.md b/Tech/software-engineering/技术文档/6.文档结构.md similarity index 93% rename from Tech/software-engineering/技术文档/文档结构.md rename to Tech/software-engineering/技术文档/6.文档结构.md index 8cb258c7..c9438392 100644 --- a/Tech/software-engineering/技术文档/文档结构.md +++ b/Tech/software-engineering/技术文档/6.文档结构.md @@ -1,14 +1,17 @@ --- title: 文档结构 -description: 文档结构 +description: 本文阐述了技术文档结构的重要性，包括合理使用标题层级、标题描述的规范、段落的组织和目录的编制。强调了标题要简洁明确、避免重复和标点，段落应有单一主题且长度适中，以及目录对快速导航的重要性。 keywords: - - 文档 - - 结构 + - 文档结构 + - 标题层级 + - 段落组织 + - 目录编制 + - 技术文档 tags: - 软件工程/技术文档 - 技术/软件工程 author: 7Wate -date: 2023-06-26 +date: 2024-08-07 --- ## 标题 diff --git a/Tech/software-engineering/技术文档/附录资料.md b/Tech/software-engineering/技术文档/7.附录资料.md similarity index 99% rename from Tech/software-engineering/技术文档/附录资料.md rename to Tech/software-engineering/技术文档/7.附录资料.md index d528fcf2..fd4bcaf7 100644 --- a/Tech/software-engineering/技术文档/附录资料.md +++ b/Tech/software-engineering/技术文档/7.附录资料.md @@ -8,7 +8,7 @@ tags: - 软件工程/技术文档 - 技术/软件工程 author: 7Wate -date: 2023-06-26 +date: 2024-08-07 --- 针对编写的一系列技术文档，应提供相应的**术语表**和**缩略语表**作为附录资料，方便读者查阅。 diff --git a/Tech/software-engineering/谷歌开源项目风格指南.md b/Tech/software-engineering/谷歌开源项目风格指南.md deleted file mode 100644 index f82d640a..00000000 --- a/Tech/software-engineering/谷歌开源项目风格指南.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -id: 谷歌开源项目风格指南 -title: 谷歌开源项目风格指南 -data: 2022年5月30日 ---- - -## 谷歌官方 - -仓库地址：[Google Style Guides](https://github.com/google/styleguide) - -在线阅读：[Google Style Guides](https://google.github.io/styleguide/) - -## 中国版 - -仓库地址：[Google 开源项目风格指南（中文版）](https://github.com/zh-google-styleguide/zh-google-styleguide) - -阅读地址：[Google 开源项目风格指南（中文版）](https://zh-google-styleguide.readthedocs.io/en/latest/)