zhouzhongping/wiki
1
0
Fork 0
Code
78d72e7788
wiki/Technology/SoftwareEngineering/技术文档/5.文档内容.html

566 lines
501 KiB
HTML
Raw Normal View History

Deploy HTML files - 2024-09-03
2024-09-03 21:23:28 +08:00
<!DOCTYPE html>
<html><head><title>文档内容</title><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><meta property="og:title" content="文档内容"/><meta property="og:description" content="本文提供了技术文档编写的详细规范，包括正确使用空白符号、列表、表格、图形图片、代码块及注释、链接和引用，以及缩略语和数字表达方式。强调了文档的清晰性、准确性和易读性，同时指出了常见的错误用法。."/><meta property="og:image" content="https://wiki.7wate.com/static/og-image.png"/><meta property="og:width" content="1200"/><meta property="og:height" content="675"/><link rel="icon" href="../../../static/icon.png"/><meta name="description" content="本文提供了技术文档编写的详细规范，包括正确使用空白符号、列表、表格、图形图片、代码块及注释、链接和引用，以及缩略语和数字表达方式。强调了文档的清晰性、准确性和易读性，同时指出了常见的错误用法。."/><meta name="generator" content="Quartz"/><link rel="preconnect" href="https://fonts.googleapis.com"/><link rel="preconnect" href="https://fonts.gstatic.com"/><script async src="https://umami.7wate.com/script.js" data-website-id="c061efdc-95dd-4d21-9d04-a1ffda0a85b9"></script><script>
var _hmt = _hmt || [];
(function() {
var hm = document.createElement("script");
hm.src = "https://hm.baidu.com/hm.js?94d8ccb156eb7c65abf317e6e01cdba9";
var s = document.getElementsByTagName("script")[0];
s.parentNode.insertBefore(hm, s);
})();
</script><script async src="https://www.googletagmanager.com/gtag/js?id=G-MHMEL0F832"></script><script>
(function() {
window.dataLayer = window.dataLayer || [];
function gtag() {
window.dataLayer.push(arguments);
}
gtag('js', new Date());
gtag('config', 'G-MHMEL0F832');
})();
</script><link href="../../../index.css" rel="stylesheet" type="text/css" spa-preserve/><link href="https://cdn.jsdelivr.net/npm/katex@0.16.0/dist/katex.min.css" rel="stylesheet" type="text/css" spa-preserve/><link href="https://fonts.googleapis.com/css2?family=IBM Plex Mono&amp;family=Schibsted Grotesk:wght@400;700&amp;family=Source Sans Pro:ital,wght@0,400;0,600;1,400;1,600&amp;display=swap" rel="stylesheet" type="text/css" spa-preserve/><script src="../../../prescript.js" type="application/javascript" spa-preserve></script><script type="application/javascript" spa-preserve>const fetchData = fetch(`../../../static/contentIndex.json`).then(data => data.json())</script></head><body data-slug="Technology/SoftwareEngineering/技术文档/5.文档内容"><div id="quartz-root" class="page"><div id="quartz-body"><div class="left sidebar"><h1 class="page-title "><a href="../../..">📚 X·Eden</a></h1><div class="spacer mobile-only"></div><div class="search "><div id="search-icon"><p>Search</p><div></div><svg tabIndex="0" aria-labelledby="title desc" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 19.9 19.7"><title id="title">Search</title><desc id="desc">Search</desc><g class="search-path" fill="none"><path stroke-linecap="square" d="M18.5 18.3l-5.4-5.4"></path><circle cx="8" cy="8" r="7"></circle></g></svg></div><div id="search-container"><div id="search-space"><input autocomplete="off" id="search-bar" name="search" type="text" aria-label="Search for something" placeholder="Search for something"/><div id="results-container"></div></div></div></div><div class="darkmode "><input class="toggle" id="darkmode-toggle" type="checkbox" tabIndex="-1"/><label id="toggle-label-light" for="darkmode-toggle" tabIndex="-1"><svg xmlns="http://www.w3.org/2000/svg" xmlnsXlink="http://www.w3.org/1999/xlink" version="1.1" id="dayIcon" x="0px" y="0px" viewBox="0 0 35 35" style="enable-background:new 0 0 35 35;" xmlSpace="preserve"><title>Light mode</title><path d="M6,17.5C6,16.672,5.328,16,4.5,16h-3C0.672,16,0,16.672,0,17.5 S0.672,19,1.5,19h3C5.328,19,6,18.328,6,17.5z M7.5,26c-0.414,0-0.789,0.168-1.061,0.439l-2,2C4.168,28.711,4,29.086,4,29.5 C4,30.328,4.671,31,5.5,31c0.414,0,0.789-0.168,1.06-0.44l2-2C8.832,28.289,9,27.914,9,27.5C9,26.672,8.329,26,7.5,26z M17.5,6 C18.329,6,19,5.328,19,4.5v-3C19,0.672,18.329,0,17.5,0S16,0.672,16,1.5v3C16,5.328,16.671,6,17.5,6z M27.5,9 c0.414,0,0.789-0.168,1.06-0.439l2-2C30.832,6.289,31,5.914,31,5.5C31,4.672,30.329,4,29.5,4c-0.414,0-0.789,0.168-1.061,0.44 l-2,2C26.168,6.711,26,7.086,26,7.5C26,8.328,26.671,9,27.5,9z M6.439,8.561C6.711,8.832,7.086,9,7.5,9C8.328,9,9,8.328,9,7.5 c0-0.414-0.168-0.789-0.439-1.061l-2-2C6.289,4.168,5.914,4,5.5,4C4.672,4,4,4.672,4,5.5c0,0.414,0.168,0.789,0.439,1.06 L6.439,8.561z M33.5,16h-3c-0.828,0-1.5,0.672-1.5,1.5s0.672,1.5,1.5,1.5h3c0.828,0,1.5-0.672,1.5-1.5S34.328,16,33.5,16z M28.561,26.439C28.289,26.168,27.914,26,27.5,26c-0.828,0-1.5,0.672-1.5,1.5c0,0.414,0.168,0.789,0.439,1.06l2,2 C28.711,30.832,29.086,31,29.5,31c0.828,0,1.5-0.672,1.5-1.5c0-0.414-0.168-0.789-0.439-1.061L28.561,26.439z M17.5,29 c-0.829,0-1.5,0.672-1.5,1.5v3c0,0.828,0.671,1.5,1.5,1.5s1.5-0.672,1.5-1.5v-3C19,29.672,18.329,29,17.5,29z M17.5,7 C11.71,7,7,11.71,7,17.5S11.71,28,17.5,28S28,23.29,28,17.5S23.29,7,17.5,7z M17.5,25c-4.136,0-7.5-3.364-7.5-7.5 c0-4.136,3.364-7.5,7.5-7.5c4.136,0,7.5,3.364,7.5,7.5C25,21.636,21.636,25,17.5,25z"></path></svg></label><label id="toggle-label-dark" for="darkmode-toggle" tabIndex="-1"><svg xmlns="http://www.w3.org/2000/svg" xmlnsXlink="http://www.w3.org/1999/xlink" version="1.1" id="nightIcon" x="0px" y="0px" viewBox="0 0 100 100" style="enable-background='new 0 0 100 100'" xmlSpace="preserve"><title>Dark mode</title><path d="M96.76,66.458c-0.853-0.852-2.15-1.064-3.23-0.534c-6.063,2.991-12.858,4.571-19.655,4.571 C62.022,70.495,50.88,65.88,42.5,57.5C29.043,44.043,25.658,23.536,34.076,6.47c0.532-1.08,0.318-2.379-0.534-3.23 c-0.851-0.852-2.15-1.064-3.23-0.534c-4.918,2.427-9.375,5.619-13.246,9.491c-9.447,9.447-14.65,22.008-14.65,35.36
<p>空白符号包括空格、空行等，其中空格分为半角空格和全角空格。</p>
<h3 id="空格">空格<a aria-hidden="true" tabindex="-1" href="#空格" class="internal"> §</a></h3>
<ul>
<li>使用半角空格，不使用全角空格；英文字符和阿拉伯数字用半角空格包围</li>
</ul>
<blockquote>
<p>这是一段□□□文本。❌</p>
<p>这是一段文本。</p>
<p>这是一段文本，包含中文、English□words□和□12345。</p>
</blockquote>
<ul>
<li>
<p>除缩进、列表级别、代码块和 Markdown 表格外，禁止连续使用半角空格。</p>
</li>
<li>
<p><strong>禁止使用 Tab 替换空格。</strong></p>
</li>
</ul>
<h3 id="空行">空行<a aria-hidden="true" tabindex="-1" href="#空行" class="internal"> §</a></h3>
<ul>
<li>不同段落间用一个空行隔开，不同排版格式之间（如标题和正文，正文和代码块，正文和表格等）也使用一个空行隔开。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);font-weight:bold;"># 这是一个标题</span></span>
<span data-line><span style="color:var(--shiki-color-text);">□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□</span></span>
<span data-line><span style="color:var(--shiki-color-text);">这是第一段。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□</span></span>
<span data-line><span style="color:var(--shiki-color-text);">这是第二段。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□</span></span></code></pre></div>
<ul>
<li>禁止连续出现两个及以上的空行。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">这是一段文本。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□</span></span>
<span data-line><span style="color:var(--shiki-color-text);">□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□</span></span>
<span data-line><span style="color:var(--shiki-color-text);">这是另一段错误的文本。❌</span></span></code></pre></div>
<h3 id="其他">其他<a aria-hidden="true" tabindex="-1" href="#其他" class="internal"> §</a></h3>
<ul>
<li>
<p>行宽在 80、120 字符中自由选择，原则上不超过 160 字符宽。</p>
</li>
<li>
<p>推荐使用空格进行缩进或对齐，禁止使用 Tab 键。</p>
</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">- 列表项1</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> - 子列表项1</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> - 子列表项2</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 列表项2</span></span></code></pre></div>
<h2 id="列表">列表<a aria-hidden="true" tabindex="-1" href="#列表" class="internal"> §</a></h2>
<ul>
<li>使用纵向列表表示多项信息。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">以下是我们需要考虑的事项：</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 项目预算</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 团队规模</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 项目时间线</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 预期成果</span></span></code></pre></div>
<ul>
<li>列表项的顺序重要时，使用有序列表。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">请按照以下步骤进行操作：</span></span>
<span data-line><span style="color:var(--shiki-color-text);">1. 打开电脑。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">2. 打开浏览器。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">3. 输入网址。</span></span></code></pre></div>
<ul>
<li>并列列表项中使用相似的句子结构，并保持标点符号一致。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">我们的团队成员包括：</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 李雷，负责产品设计。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 韩梅梅，负责项目管理。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- Jim，负责软件开发。</span></span></code></pre></div>
<ul>
<li>使用清晰的、描述性的句子或短语来引出表。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">以下是我们团队的主要职责：</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 设计和开发新产品。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 维护现有产品。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 提供客户支持。</span></span></code></pre></div>
<ul>
<li>使用有序列表描述操作任务的步骤。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">使用该软件的步骤如下：</span></span>
<span data-line><span style="color:var(--shiki-color-text);">1. 下载并安装软件。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">2. 运行软件并点击 &quot;新建项目&quot;。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">3. 输入项目详情并保存。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">4. 开始使用软件进行项目管理。</span></span></code></pre></div>
<ul>
<li>嵌套使用列表，最多不超过 3 级。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">本产品主要包括以下部分：</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 外壳</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> - 上盖</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> - 下盖</span></span>
<span data-line><span style="color:var(--shiki-color-text);">- 内部组件</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> - CPU</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> - 内存</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> - 硬盘</span></span></code></pre></div>
<h2 id="表格">表格<a aria-hidden="true" tabindex="-1" href="#表格" class="internal"> §</a></h2>
<ul>
<li>所有内容保持左对齐，内容尽量简练，避免长篇大段的说明，不出现空白的单元格，单元格内容避免重复。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">| 表头1 | 表头2 | 表头3 |</span></span>
<span data-line><span style="color:var(--shiki-color-text);">|:-------|:-------|:-------|</span></span>
<span data-line><span style="color:var(--shiki-color-text);">| 内容1 | 内容2 | 内容3 |</span></span>
<span data-line><span style="color:var(--shiki-color-text);">| 内容4 | 内容5 | 内容6 |</span></span></code></pre></div>
<ul>
<li>表格需要有表头描述，同一文档中相同类型表格的表头描述需要保持一致。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">| 姓名 | 年龄 | 职业 |</span></span>
<span data-line><span style="color:var(--shiki-color-text);">|:-------|:-----|:-----|</span></span>
<span data-line><span style="color:var(--shiki-color-text);">| 张三 | 25 | 程序员 |</span></span>
<span data-line><span style="color:var(--shiki-color-text);">| 李四 | 30 | 设计师 |</span></span></code></pre></div>
<ul>
<li>每个表格下都要空一行，空行的样式为正文。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">| 姓名 | 年龄 | 职业 |</span></span>
<span data-line><span style="color:var(--shiki-color-text);">|:-------|:-----|:-----|</span></span>
<span data-line><span style="color:var(--shiki-color-text);">| 张三 | 25 | 程序员 |</span></span>
<span data-line><span style="color:var(--shiki-color-text);">| 李四 | 30 | 设计师 |</span></span>
<span data-line><span style="color:var(--shiki-color-text);">□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□</span></span>
<span data-line><span style="color:var(--shiki-color-text);">这是正文部分</span></span></code></pre></div>
<h2 id="图形和图片">图形和图片<a aria-hidden="true" tabindex="-1" href="#图形和图片" class="internal"> §</a></h2>
<ul>
<li><strong>必须使用清晰可辨的图形图片。</strong></li>
<li>中文文档里图形图片上的文字建议都用中文，如果原图文字是其他语言，应该先做好图片本地化工作。</li>
<li>文字建议使用<strong>免费开源可商用字体</strong>，以免引入法律风险。同一文档内图形图片上的中文应该统一字体（如思源黑体），英文和数字也要统一字体（如 Times New Roman）。</li>
<li>图形图片中避免出现大段文字，描述性语言建议放到图外，用编号替代。</li>
<li>图形图片中包含缩略语时，需要在图说明中对缩略语进行解释。</li>
<li>图说明和图尽量保证在同一页中显示。</li>
<li>图片的命名建议使用描述性的文字。</li>
<li>插入图片时建议添加替代文本，从而改进文档的可访问性。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">![</span><span style="color:var(--shiki-token-keyword);">描述图片内容</span><span style="color:var(--shiki-color-text);">]</span><span style="color:var(--shiki-token-link);">(/path/to/image.jpg</span><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-keyword);">&quot;</span><span style="color:var(--shiki-token-string);">图片标题，可选填</span><span style="color:var(--shiki-token-keyword);">&quot;</span><span style="color:var(--shiki-token-link);">)</span></span>
<span data-line> </span>
<span data-line><span style="color:var(--shiki-color-text);">- </span><span style="color:var(--shiki-color-text);font-weight:bold;">**说明**</span><span style="color:var(--shiki-color-text);">：图1. 这是一幅示例图片。其中的文字全部使用了中文，并且字体统一为思源黑体。对于图中的缩略语，我们在这里进行解释：XYZ代表的是...</span></span></code></pre></div>
<h2 id="代码块和代码注释">代码块和代码注释<a aria-hidden="true" tabindex="-1" href="#代码块和代码注释" class="internal"> §</a></h2>
<ul>
<li>如果代码块语言被支持，那么应该明确声明语言类型。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-token-string);"> ```python</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-comment);"># 这是一个 Python 示例</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-function);">print</span><span style="color:var(--shiki-token-punctuation);">(</span><span style="color:var(--shiki-token-string-expression);">&quot;Hello, World!&quot;</span><span style="color:var(--shiki-token-punctuation);">)</span></span>
<span data-line><span style="color:var(--shiki-token-string);"> ```</span></span></code></pre></div>
<ul>
<li>代码块中出现的长命令应当按逻辑进行换行，并且注明需要换行的地方。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-token-string);"> ```bash</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-comment);"># 在这个长命令中，我们使用 \ 来进行换行</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-function);">command</span><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-string);">--option1</span><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-string);">--option2</span><span style="color:var(--shiki-color-text);"> \</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> --option3 --option4 --option5</span></span>
<span data-line><span style="color:var(--shiki-token-string);"> ```</span></span></code></pre></div>
<ul>
<li>代码块中的命令，如需参数替换，应该清晰标注。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-token-string);"> ```bash</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-comment);"># 在这个命令中，&lt;username> 需要被你的用户名替换</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-function);">ssh</span><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-keyword);">&lt;</span><span style="color:var(--shiki-token-string);">usernam</span><span style="color:var(--shiki-color-text);">e</span><span style="color:var(--shiki-token-keyword);">></span><span style="color:var(--shiki-token-string);">@example.com</span></span>
<span data-line><span style="color:var(--shiki-token-string);"> ```</span></span></code></pre></div>
<ul>
<li>代码块中不应当出现警告或者错误信息，除非它们是文章需要表达的内容。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-token-string);"> ```python</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-comment);"># 这个 Python 示例没有任何错误或警告</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-keyword);">def</span><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-function);">greet</span><span style="color:var(--shiki-color-text);">(</span><span style="color:var(--shiki-token-parameter);">name</span><span style="color:var(--shiki-color-text);">):</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-function);">print</span><span style="color:var(--shiki-token-punctuation);">(</span><span style="color:var(--shiki-token-keyword);">f</span><span style="color:var(--shiki-token-string-expression);">&quot;Hello, </span><span style="color:var(--shiki-token-constant);">{</span><span style="color:var(--shiki-token-punctuation);">name</span><span style="color:var(--shiki-token-constant);">}</span><span style="color:var(--shiki-token-string-expression);">!&quot;</span><span style="color:var(--shiki-token-punctuation);">)</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-function);">greet</span><span style="color:var(--shiki-token-punctuation);">(</span><span style="color:var(--shiki-token-string-expression);">&quot;World&quot;</span><span style="color:var(--shiki-token-punctuation);">)</span></span>
<span data-line><span style="color:var(--shiki-token-string);"> ```</span></span></code></pre></div>
<ul>
<li>代码注释需要使用英文，并且注释要简洁明了，且必须准确。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-token-string);"> ```python</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-comment);"># Correct and concise comment: Print greeting</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-function);">print</span><span style="color:var(--shiki-token-punctuation);">(</span><span style="color:var(--shiki-token-string-expression);">&quot;Hello, World!&quot;</span><span style="color:var(--shiki-token-punctuation);">)</span><span style="color:var(--shiki-color-text);"> </span></span>
<span data-line><span style="color:var(--shiki-token-string);"> ```</span></span></code></pre></div>
<ul>
<li>如果代码块中的注释和文章内容重复，那么优先使用代码块中的注释，同时去掉文章中的内容。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-token-string);"> ```python</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-comment);"># This comment explains the following code block</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-function);">print</span><span style="color:var(--shiki-token-punctuation);">(</span><span style="color:var(--shiki-token-string-expression);">&quot;Hello, World!&quot;</span><span style="color:var(--shiki-token-punctuation);">)</span><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-comment);"># This line prints a greeting</span></span>
<span data-line><span style="color:var(--shiki-token-string);"> ```</span></span></code></pre></div>
<h2 id="链接和引用">链接和引用<a aria-hidden="true" tabindex="-1" href="#链接和引用" class="internal"> §</a></h2>
<ul>
<li>链接和引用必须给出精确的位置信息。例如，如果你正在引用一个具体的 GitHub 代码行：</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">看一下 </span><span style="color:var(--shiki-token-constant);text-decoration:underline;">[</span><span style="color:var(--shiki-token-keyword);text-decoration:underline;">这个具体的代码行</span><span style="color:var(--shiki-token-constant);text-decoration:underline;">]</span><span style="color:var(--shiki-token-link);text-decoration:underline;">(https://github.com/user/repository/blob/master/file.py#L42)</span><span style="color:var(--shiki-color-text);"> 来理解如何实现这个功能。</span></span></code></pre></div>
<ul>
<li>如果链接和引用的位置有更新，必须及时更新链接。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">由于最新的更新，参考 </span><span style="color:var(--shiki-token-constant);text-decoration:underline;">[</span><span style="color:var(--shiki-token-keyword);text-decoration:underline;">新的代码实现</span><span style="color:var(--shiki-token-constant);text-decoration:underline;">]</span><span style="color:var(--shiki-token-link);text-decoration:underline;">(https://github.com/user/repository/blob/master/new_file.py#L50)</span><span style="color:var(--shiki-color-text);">。</span></span></code></pre></div>
<ul>
<li>链接和引用中出现的代码，必须使用代码块包围。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">参考以下代码实现：</span></span>
<span data-line> </span>
<span data-line><span style="color:var(--shiki-token-string);"> ```python</span></span>
<span data-line><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-keyword);">def</span><span style="color:var(--shiki-color-text);"> </span><span style="color:var(--shiki-token-function);">greet</span><span style="color:var(--shiki-color-text);">(</span><span style="color:var(--shiki-token-parameter);">name</span><span style="color:var(--shiki-color-text);">):</span></span>
<span data-line><span style="color:var(--shiki-token-string);"> ```</span></span></code></pre></div>
<ul>
<li>必须标注链接的类型，如文章、工具、命令等。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">阅读这篇 </span><span style="color:var(--shiki-token-constant);text-decoration:underline;">[</span><span style="color:var(--shiki-token-keyword);text-decoration:underline;">文章</span><span style="color:var(--shiki-token-constant);text-decoration:underline;">]</span><span style="color:var(--shiki-token-link);text-decoration:underline;">(https://example.com/article)</span><span style="color:var(--shiki-color-text);"> 来更深入地了解这个主题。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">使用这个 </span><span style="color:var(--shiki-token-constant);text-decoration:underline;">[</span><span style="color:var(--shiki-token-keyword);text-decoration:underline;">工具</span><span style="color:var(--shiki-token-constant);text-decoration:underline;">]</span><span style="color:var(--shiki-token-link);text-decoration:underline;">(https://example.com/tool)</span><span style="color:var(--shiki-color-text);"> 来帮助你的开发工作。</span></span>
<span data-line><span style="color:var(--shiki-color-text);">运行以下 </span><span style="color:var(--shiki-token-constant);text-decoration:underline;">[</span><span style="color:var(--shiki-token-keyword);text-decoration:underline;">命令</span><span style="color:var(--shiki-token-constant);text-decoration:underline;">]</span><span style="color:var(--shiki-token-link);text-decoration:underline;">(https://example.com/command)</span><span style="color:var(--shiki-color-text);"> 来配置你的环境。</span></span></code></pre></div>
<ul>
<li>每个文件的引用必须声明来源，使用全称，不要使用相对路径或者绝对路径。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">引用自 </span><span style="color:var(--shiki-token-constant);text-decoration:underline;">[</span><span style="color:var(--shiki-token-keyword);text-decoration:underline;">Python官方文档</span><span style="color:var(--shiki-token-constant);text-decoration:underline;">]</span><span style="color:var(--shiki-token-link);text-decoration:underline;">(https://docs.python.org/3/tutorial/index.html)</span><span style="color:var(--shiki-color-text);">，不是 </span><span style="color:var(--shiki-token-string);">`../tutorial/index.html`</span><span style="color:var(--shiki-color-text);"> 或者 </span><span style="color:var(--shiki-token-string);">`/home/user/docs/tutorial/index.html`</span><span style="color:var(--shiki-color-text);">。</span></span></code></pre></div>
<ul>
<li>不能使用会失效的链接。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">请使用 </span><span style="color:var(--shiki-token-constant);text-decoration:underline;">[</span><span style="color:var(--shiki-token-keyword);text-decoration:underline;">永久链接</span><span style="color:var(--shiki-token-constant);text-decoration:underline;">]</span><span style="color:var(--shiki-token-link);text-decoration:underline;">(https://example.com/permanent-link)</span><span style="color:var(--shiki-color-text);">，而不是 </span><span style="color:var(--shiki-token-constant);text-decoration:underline;">[</span><span style="color:var(--shiki-token-keyword);text-decoration:underline;">会失效的链接</span><span style="color:var(--shiki-token-constant);text-decoration:underline;">]</span><span style="color:var(--shiki-token-link);text-decoration:underline;">(https://example.com/temporary-link)</span><span style="color:var(--shiki-color-text);">。</span></span></code></pre></div>
<ul>
<li>链接的文字应描述其链接的内容，而不应为「这里」、「此处」等模糊词汇。</li>
</ul>
<div data-rehype-pretty-code-fragment><pre style="background-color:var(--shiki-color-background);" tabindex="0" data-language="markdown" data-theme="default"><code data-language="markdown" data-theme="default"><span data-line><span style="color:var(--shiki-color-text);">阅读 </span><span style="color:var(--shiki-token-constant);text-decoration:underline;">[</span><span style="color:var(--shiki-token-keyword);text-decoration:underline;">Python教程</span><span style="color:var(--shiki-token-constant);text-decoration:underline;">]</span><span style="color:var(--shiki-token-link);text-decoration:underline;">(https://docs.python.org/3/tutorial/index.html)</span><span style="color:var(--shiki-color-text);">，而不是点击 </span><span style="color:var(--shiki-token-constant);text-decoration:underline;">[</span><span style="color:var(--shiki-token-keyword);text-decoration:underline;">这里</span><span style="color:var(--shiki-token-constant);text-decoration:underline;">]</span><span style="color:var(--shiki-token-link);text-decoration:underline;">(https://docs.python.org/3/tutorial/index.html)</span><span style="color:var(--shiki-color-text);">。</span></span></code></pre></div>
<h2 id="缩略语">缩略语<a aria-hidden="true" tabindex="-1" href="#缩略语" class="internal"> §</a></h2>
<p>在编写中文技术文档时，我们常会用到两类缩略语：汉语缩略语和英语缩略语。</p>
<h3 id="汉语缩略语">汉语缩略语<a aria-hidden="true" tabindex="-1" href="#汉语缩略语" class="internal"> §</a></h3>
<p>汉语缩略语是通过缩短和省略较长的中文词语来形成的新词。例如，「人大」是「人民大会堂」的缩略，而「重启」则是「重启动」的缩略。</p>
<p>**使用汉语缩略语时，我们要确保这些词在上下文中的含义清晰、准确，以避免产生歧义。**如果某个汉语缩略语并非大众常用或容易理解，我们在初次使用时应提供全称和相应的解释。例如，如果我们在文档中使用「绑核」作为「核心绑定」的缩略，我们需要在初次使用时指出：「本文将使用 ’ 绑核 ’ 作为 ’ 核心绑定 ’ 的缩略」。</p>
<h3 id="英语缩略语">英语缩略语<a aria-hidden="true" tabindex="-1" href="#英语缩略语" class="internal"> §</a></h3>
<p>相较于汉语缩略语，英语缩略语种类繁多，数量众多。一般来说，它们分为三类：<strong>首字母缩略词、字母词和缩写词。</strong></p>
<ul>
<li>
<p>首字母缩略词：这类缩略词是由每个单词的首字母组合而成，且作为一个单词发音。如「NATO」（North Atlantic Treaty Organization），我们读作 /‘neɪtoʊ/，而<strong>非逐字母发音。</strong></p>
</li>
<li>
<p>字母词：与首字母缩略词类似，也是由每个词的首字母组成，但是按字母逐一发音。例如，「FBI」（Federal Bureau of Investigation），我们会读作 /‘efbi:‘aɪ/，而<strong>非作为一个单词发音。</strong></p>
</li>
<li>
<p>缩写词：直接将较长的词语进行缩短形成新词。例如，「App」是「Application」的缩写词，「demo」则是「demonstration」的缩写词。我们读作 /‘æp/，而<strong>非逐字母发音。</strong></p>
</li>
</ul>
<p>在使用英语缩略语时，我们需要注意以下几点：</p>
<ul>
<li>
<p>在标题中，避免对英文缩略语进行解释，以免使标题过长，影响阅读。</p>
</li>
<li>
<p>在正文中，首次出现的英文缩略语需要提供其完整形式和对应的解释。例如，如果我们首次使用「AI」，我们需要指出：「AI（Artificial Intelligence，人工智能）」。</p>
</li>
<li>
<p>当使用缩略语代指某词时，必须在该词首次出现时告知读者，下文将以缩略语的形式称呼该词。</p>
</li>
<li>
<p>不要使用非标准的或可能引起混淆的缩略语，例如，「16c32g」不能用来表示「16 核、32GB」，「10w」也不能用来表示「10 万」。</p>
</li>
</ul>
<h2 id="数字">数字<a aria-hidden="true" tabindex="-1" href="#数字" class="internal"> §</a></h2>
<p>在中文语境中，数字有两种形式：第一种是汉字数字，如「二」、「十」等；第二种是阿拉伯数字，如「2」、「10」等。</p>
<h3 id="汉字数字">汉字数字<a aria-hidden="true" tabindex="-1" href="#汉字数字" class="internal"> §</a></h3>
<p><strong>汉字数字主要用于表示概数、干支纪年、含有汉字数字的词语，以及突出庄重典雅的效果。</strong></p>
<ul>
<li>概数表达：数字连用表示概数时，不用顿号隔开。例如： <code>三四十</code>。</li>
<li>年份简写：年份简写后的数字不应简写为两位数字。例如： <code>二〇二三</code> 而不是 <code>二三</code>。</li>
<li>月日的专名：含有月日的专名中，使用间隔号「·」将数字分开，并在前后加引号，避免歧义。例如： <code>&quot;六·二六&quot;</code>。</li>
<li>法律文书和财务票据：大写汉字数字用于法律文书和财务票据。例如： <code>肆仟贰佰叁拾肆元整</code>。</li>
<li>计量和编号：「零」用于计量，「〇」用于编号。例如： <code>十零个苹果</code>， <code>编号〇一〇二</code>。</li>
</ul>
<table><thead><tr><th>适用场景</th><th>示例</th></tr></thead><tbody><tr><td>数字连用表示的概数、含「几」的概数等</td><td>三四个月、一二十个、十五六岁、五六万套、五六十年前、几千、二十几、一百几十、几十万分之一</td></tr><tr><td>干支纪年、农历月日、历史朝代纪年及其他传统上采用汉字形式的非公历纪年</td><td>腊月二十三、正月初五、八月十五中秋、秦文公四十四年、太平天国庚申十年九月二十三号、日本庆应三年、丙寅年十月十五日</td></tr><tr><td>汉语中长期使用且已稳定下来的包含汉字数字形式的词语</td><td>星期五、四氧化三铁、一方面、不二法门、二八年华、二百五、八国联军、五四运动、万一、一旦、四书五经、七上八下、不管三七二十一、半斤八两、「一·二八」事变、「一·二九」运动</td></tr><tr><td>希望突出庄重典雅的表达效果时</td><td>六方会谈（不写为「6 方会谈」）、十一届全国人大一次会议（不写为「11 届全国人大 1 次会议」）</td></tr></tbody></table>
<h3 id="阿拉伯数字">阿拉伯数字<a aria-hidden="true" tabindex="-1" href="#阿拉伯数字" class="internal"> §</a></h3>
<p><strong>阿拉伯数字主要用于计量、编号、现代社会生活中的事物和现象，以及突出简洁醒目的效果。</strong></p>
<ul>
<li>
<p>形式书写：使用半角形式书写，避免使用全角形式。例如： <code>2023</code> 而不是 <code>２０２３</code>。</p>
</li>
<li>
<p>分节符：使用半角逗号作为分节符。例如： <code>1,000,000</code> 而不是 <code>1000000</code>。</p>
</li>
<li>
<p>表达范围：表示数值范围时使用浪纹式连接号「～」或一字线连接号「—」。例如： <code>10～20</code> 或 <code>10—20</code>。</p>
</li>
<li>
<p>日期和时间：年月日和时分秒的表达顺序按照口语中的自然顺序。例如： <code>2023年6月26日</code> 或 <code>15:30:00</code>。</p>
</li>
<li>
<p>月日的专名：含有月日的专名中，使用间隔号「·」将数字分开，并在前后加引号，避免歧义。例如： <code>&quot;6·26&quot;</code>。</p>
</li>
</ul>
<table><thead><tr><th>适用场景</th><th>示例</th></tr></thead><tbody><tr><td>用于计量（即用于加、减、乘、除等数学运算）的数字，如正负整数、小数、百分比、比例、分数等。</td><td>-126、34.05%、63%～67%、1:500、87/90</td></tr><tr><td>当数值伴随有计量单位，如长度、容积、面积、体积、质量、温度、经纬度、音量、频率等，特别是当计量单位以字母表达时</td><td>524.5 km（524.5 千米）、53 MB（53 兆字节）、12 h（12 小时）</td></tr><tr><td>用于编号的数字</td><td>- 电话号码：98888 - 邮政编码：100083 - 电子邮件地址：<a href="mailto:xxx@163.com" class="external">xxx@163.com</a> - 网页地址：<a href="http://127.0.0.1/" class="external">http://127.0.0.1</a> - 章节编号：4.1.2 - 产品型号：PH-3000 型计算机 - 产品序列号：C84XB-JYVFD-P7HC4-6XKRJ-7M6XH - 汽车号牌：京 A00001 - 公交车号： 302 路公交车 - 道路编号：101 国道 - 公文编号：国办发 [1987]9 号 - 图书编号：ISBN 978-7-80184-224-4 - 刊物编号：CN11-1389 - 单位注册号：02050214 - 行政许可登记编号：0684D10004-828</td></tr><tr><td>现代社会生活中出现的事物、现象、事件，其名称的书写形式中包含阿拉伯数字，已经广泛使用而稳定下来</td><td>4G 手机、MP4 播放器、维生素 B12、「5·27」事件</td></tr><tr><td>希望突出简洁醒目的表达效果时</td><td>北京时间 2020 年 10 月 1 日 12 点整</td></tr></tbody></table>
<h3 id="单位符号">单位符号<a aria-hidden="true" tabindex="-1" href="#单位符号" class="internal"> §</a></h3>
<ul>
<li>
<p>汉字名称：建议用汉字名称代替单位符号。例如： <code>三米</code> 而不是 <code>3m</code>。</p>
</li>
<li>
<p>间隔空格：数值和单位之间通常需要空一个半角空格，但有例外情况。例如： <code>3□kg</code>。</p>
</li>
<li>
<p>角度、摄氏度和百分号：角度、摄氏度和百分号的单位与数值之间不空格。例如： <code>45°</code>、 <code>20°C</code> 或 <code>50%</code>。</p>
</li>
<li>
<p>英尺符号和英寸符号：英尺符号和英寸符号与数值之间不空格。例如： <code>6'2&quot;</code>。</p>
</li>
</ul>
<table><thead><tr><th>单位形式</th><th>示例</th></tr></thead><tbody><tr><td>汉字名称</td><td>三米</td></tr><tr><td>间隔空格</td><td>3□kg</td></tr><tr><td>角度、摄氏度和百分号</td><td>45°、20°C、50%</td></tr><tr><td>英尺符号和英寸符号</td><td>6’2”</td></tr></tbody></table>
<h2 id="拼写">拼写<a aria-hidden="true" tabindex="-1" href="#拼写" class="internal"> §</a></h2>
<p>中文技术文档既包含中文内容，也可能包含英文内容。因此，我们必须避免以下几种拼写错误。</p>
<ul>
<li>禁止简体中文和繁体中文的混用。</li>
</ul>
<blockquote>
<p>这款软件的颜色设计很独特，它的界面顏色是由用户自己选择的。❌</p>
<p>正确示例：这款软件的颜色设计很独特，它的界面颜色是由用户自己选择的。</p>
</blockquote>
<ul>
<li>禁止出现中英文错别字。错别字包括错字和别字。</li>
</ul>
<blockquote>
<p>这款软件使用 MySOL 数据库存储数据。❌</p>
<p>这款软件使用 MySQL 数据库存储数据。</p>
</blockquote>
<h3 id="英文的大小写形式">英文的大小写形式<a aria-hidden="true" tabindex="-1" href="#英文的大小写形式" class="internal"> §</a></h3>
<ul>
<li>英文大小写形式不能写错。</li>
</ul>
<blockquote>
<p>用户可以在 mysql 数据库中创建新的表。❌</p>
<p>用户可以在 MySQL 数据库中创建新的表。</p>
</blockquote>
<ul>
<li>当中文句子中夹有英文单词或词组时，无论该英文单词或词组位于中文句子的开头、中间还是末尾，普通单词、词组必须小写；专有名词等在英文中必须大写的单词或词组，保留其大写形式。</li>
</ul>
<blockquote>
<p>在 SQL 语句中，你可以使用 “SELECT” 语句获取数据。❌</p>
<p>在 SQL 语句中，你可以使用 “select” 语句获取数据。</p>
</blockquote>
<ul>
<li>当中文句子中夹有完整的英文句子时，无论该英文句子位于中文句子的开头、中间还是末尾，其首字母均保留大写形式。</li>
</ul>
<blockquote>
<p>如需更多信息，请参阅 “in this chapter, we will learn how to create tables.“❌</p>
<p>如需更多信息，请参阅 “In this chapter, we will learn how to create tables.”</p>
</blockquote>
<h2 id="语法">语法<a aria-hidden="true" tabindex="-1" href="#语法" class="internal"> §</a></h2>
<h3 id="成分残缺">成分残缺<a aria-hidden="true" tabindex="-1" href="#成分残缺" class="internal"> §</a></h3>
<p>在编写技术文档时，务必确保语句的成分完整。每个句子都应该有一个明确的主语和谓语，以及必要的宾语和定语。</p>
<blockquote>
<p>会话保持：在应用程序没有提供会话保持的功能下，HAProxy 可以提供该项功能。❌</p>
<p>会话保持：在应用程序没有提供会话保持功能的情况下，HAProxy 可以提供该项功能。</p>
</blockquote>
<h3 id="搭配不当">搭配不当<a aria-hidden="true" tabindex="-1" href="#搭配不当" class="internal"> §</a></h3>
<p>确保你的句子中使用的词汇是搭配恰当的。不正确的词汇搭配可能会让读者混淆，影响他们对你的文档的理解。</p>
<blockquote>
<p>HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，并仍然负责该项目的维护，该在开源社区提供免费和版本迭代。❌</p>
<p>HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，他现在仍然负责该项目的维护，并在开源社区免费提供版本迭代。</p>
</blockquote>
<h3 id="倍数表达">倍数表达<a aria-hidden="true" tabindex="-1" href="#倍数表达" class="internal"> §</a></h3>
<p>技术文档中表达倍数建议遵循以下规范。</p>
<ul>
<li>数值的增加必须明确使用「增加了」或「增加到」，不能只使用「增加」。「了」表增量，「到」表定量。</li>
<li>数值的减少必须明确使用「降低了」或「降低到」，不能只使用「降低」。「了」表增量，「到」表定量。</li>
<li>不能用「降低 N 倍」或「减少 N 倍」的表示法，要用「降低百分之几」或「减少百分之几」。</li>
</ul>
<table><thead><tr><th>表述方式</th><th>示例</th><th>校验</th></tr></thead><tbody><tr><td>增加了</td><td>处理速度增加了两倍。</td><td>✔</td></tr><tr><td>只用增加</td><td>处理速度增加两倍。</td><td>❌</td></tr><tr><td>增加到</td><td>处理速度增加到两倍。</td><td>✔</td></tr><tr><td>只用增加</td><td>处理速度增加两倍。</td><td>❌</td></tr><tr><td>降低了</td><td>处理速度降低了五十百分点。</td><td>✔</td></tr><tr><td>降低 N 倍</td><td>处理速度降低两倍。</td><td>❌</td></tr></tbody></table>
<h3 id="成分多余">成分多余<a aria-hidden="true" tabindex="-1" href="#成分多余" class="internal"> §</a></h3>
<p>避免在句子中使用不必要的词汇或短语，这可能会使句子变得冗长和复杂，影响其清晰度和可读性。</p>
<blockquote>
<p>根据官方建议，目前稳定版本的 HAProxy 为稳定版 2.0 特性。❌</p>
<p>官方目前建议使用 HAProxy 稳定版本 2.0。</p>
</blockquote>
<h3 id="句式杂糅">句式杂糅<a aria-hidden="true" tabindex="-1" href="#句式杂糅" class="internal"> §</a></h3>
<p>避免在一个句子中混合使用多种句式。尽量保持句子简洁明了，如果需要表达的信息较多，可以考虑分解为多个句子。</p>
<blockquote>
<p>当部署多个 DM-master 节点时，所有 DM-master 节点将使用内部嵌入的 etcd 组成集群并用于存储集群节点信息、任务配置等元数据，同时通过 etcd 选举出 leader 节点用于提供集群管理、数据迁移任务管理相关的各类服务。因此，若 DM-master 可用节点数超过部署节点的半数，即可正常提供服务。❌</p>
<p>当部署多个 DM-master 节点时，所有 DM-master 节点将使用内部嵌入的 etcd 组成集群。该 DM-master 集群用于存储集群节点信息、任务配置等元数据，同时通过 etcd 选举出 leader 节点。该 leader 节点用于提供集群管理、数据迁移任务管理相关的各类服务。因此，若可用的 DM-master 节点数超过部署节点的半数，即可正常提供服务。</p>
</blockquote></article></div><div class="right sidebar"><div class="graph "><h3>Graph View</h3><div class="graph-outer"><div id="graph-container" data-cfg="{&quot;drag&quot;:true,&quot;zoom&quot;:true,&quot;depth&quot;:1,&quot;scale&quot;:1.1,&quot;repelForce&quot;:0.5,&quot;centerForce&quot;:0.3,&quot;linkDistance&quot;:30,&quot;fontSize&quot;:0.6,&quot;opacityScale&quot;:1,&quot;showTags&quot;:true,&quot;removeTags&quot;:[]}"></div><svg version="1.1" id="global-graph-icon" xmlns="http://www.w3.org/2000/svg" xmlnsXlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 55 55" fill="currentColor" xmlSpace="preserve"><path d="M49,0c-3.309,0-6,2.691-6,6c0,1.035,0.263,2.009,0.726,2.86l-9.829,9.829C32.542,17.634,30.846,17,29,17
s-3.542,0.634-4.898,1.688l-7.669-7.669C16.785,10.424,17,9.74,17,9c0-2.206-1.794-4-4-4S9,6.794,9,9s1.794,4,4,4
c0.74,0,1.424-0.215,2.019-0.567l7.669,7.669C21.634,21.458,21,23.154,21,25s0.634,3.542,1.688,4.897L10.024,42.562
C8.958,41.595,7.549,41,6,41c-3.309,0-6,2.691-6,6s2.691,6,6,6s6-2.691,6-6c0-1.035-0.263-2.009-0.726-2.86l12.829-12.829
c1.106,0.86,2.44,1.436,3.898,1.619v10.16c-2.833,0.478-5,2.942-5,5.91c0,3.309,2.691,6,6,6s6-2.691,6-6c0-2.967-2.167-5.431-5-5.91
v-10.16c1.458-0.183,2.792-0.759,3.898-1.619l7.669,7.669C41.215,39.576,41,40.26,41,41c0,2.206,1.794,4,4,4s4-1.794,4-4
s-1.794-4-4-4c-0.74,0-1.424,0.215-2.019,0.567l-7.669-7.669C36.366,28.542,37,26.846,37,25s-0.634-3.542-1.688-4.897l9.665-9.665
C46.042,11.405,47.451,12,49,12c3.309,0,6-2.691,6-6S52.309,0,49,0z M11,9c0-1.103,0.897-2,2-2s2,0.897,2,2s-0.897,2-2,2
S11,10.103,11,9z M6,51c-2.206,0-4-1.794-4-4s1.794-4,4-4s4,1.794,4,4S8.206,51,6,51z M33,49c0,2.206-1.794,4-4,4s-4-1.794-4-4
s1.794-4,4-4S33,46.794,33,49z M29,31c-3.309,0-6-2.691-6-6s2.691-6,6-6s6,2.691,6,6S32.309,31,29,31z M47,41c0,1.103-0.897,2-2,2
s-2-0.897-2-2s0.897-2,2-2S47,39.897,47,41z M49,10c-2.206,0-4-1.794-4-4s1.794-4,4-4s4,1.794,4,4S51.206,10,49,10z"></path></svg></div><div id="global-graph-outer"><div id="global-graph-container" data-cfg="{&quot;drag&quot;:true,&quot;zoom&quot;:true,&quot;depth&quot;:-1,&quot;scale&quot;:0.9,&quot;repelForce&quot;:0.5,&quot;centerForce&quot;:0.3,&quot;linkDistance&quot;:30,&quot;fontSize&quot;:0.6,&quot;opacityScale&quot;:1,&quot;showTags&quot;:true,&quot;removeTags&quot;:[]}"></div></div></div><div class="toc desktop-only"><button type="button" id="toc" class><h3>Table of Contents</h3><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="fold"><polyline points="6 9 12 15 18 9"></polyline></svg></button><div id="toc-content"><ul class="overflow"><li class="depth-0"><a href="#空白符号" data-for="空白符号">空白符号</a></li><li class="depth-1"><a href="#空格" data-for="空格">空格</a></li><li class="depth-1"><a href="#空行" data-for="空行">空行</a></li><li class="depth-1"><a href="#其他" data-for="其他">其他</a></li><li class="depth-0"><a href="#列表" data-for="列表">列表</a></li><li class="depth-0"><a href="#表格" data-for="表格">表格</a></li><li class="depth-0"><a href="#图形和图片" data-for="图形和图片">图形和图片</a></li><li class="depth-0"><a href="#代码块和代码注释" data-for="代码块和代码注释">代码块和代码注释</a></li><li class="depth-0"><a href="#链接和引用" data-for="链接和引用">链接和引用</a></li><li class="depth-0"><a href="#缩略语" data-for="缩略语">缩略语</a></li><li class="depth-1"><a href="#汉语缩略语" data-for="汉语缩略语">汉语缩略语</a></li><li class="depth-1"><a href="#英语缩略语" data-for="英语缩略语">英语缩略语</a></li><li class="depth-0"><a href="#数字" data-for="数字">数字</a></li><li class="depth-1"><a href="#汉字数字" data-for="汉字数字">汉字数字</a></li><li class="depth-1"><a href="#阿拉伯数字" data-for="阿拉伯数字">阿拉伯数字</a></li><li class="depth-1"><a href="#单位符号" data-for="单位符号">单位符号</a></li><li class="depth-0"><a href="#拼写" data-for="拼写">拼写</a></li><li class="depth-1"><a href="#英文的大小写形式" data-for="英文的大小写形式">英文的大小写形式</a></li><li class="depth-0"><a href="#语法" data-for="语法">语法</a></li><li class="depth-1"><a href="#成分残缺" data-for="成分残缺">成分残缺</a></li><li class="depth-1"><a href="#搭配不当" data-for="搭配不当">搭配不当</a></li><li class="depth-1"><a href="#倍数表达" data-for="倍数表达">倍数表达</a></li><li class="depth-1"><a href="#成分多余" data-for="成分多余">成分多余</a></li><li class="depth-1"><a href="#句式杂糅" data-for="句式杂糅">句式杂糅</a></li></ul></div></div><div class="backlinks "><h3>Backlinks</h3><ul class="overflow"><li>No backlinks found</li></ul></div><div class="explorer mobile-only"><button type="button" id="explorer" data-behavior="collapse" data-collapsed="collapsed" data-savestate="true" data-tree="[{&quot;path&quot;:&quot;Journal&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Journal/2024&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Journal/2024/W33&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Obsidian&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Obsidian/Templates&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Personal&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Personal/Blog&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Personal/Blog/2018&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Personal/Blog/2020&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Personal/Blog/2021&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Personal/Blog/2022&quot;,&quot;collapsed&quot;:true},{&quot;path&quot;:&quot;Pers
function toggleCallout() {
const outerBlock = this.parentElement;
outerBlock.classList.toggle(`is-collapsed`);
const collapsed = outerBlock.classList.contains(`is-collapsed`);
const height = collapsed ? this.scrollHeight : outerBlock.scrollHeight;
outerBlock.style.maxHeight = height + `px`;
let current = outerBlock;
let parent = outerBlock.parentElement;
while (parent) {
if (!parent.classList.contains(`callout`)) {
return;
}
const collapsed2 = parent.classList.contains(`is-collapsed`);
const height2 = collapsed2 ? parent.scrollHeight : parent.scrollHeight + current.scrollHeight;
parent.style.maxHeight = height2 + `px`;
current = parent;
parent = parent.parentElement;
}
}
function setupCallout() {
const collapsible = document.getElementsByClassName(
`callout is-collapsible`
);
for (const div of collapsible) {
const title = div.firstElementChild;
if (title) {
title.removeEventListener(`click`, toggleCallout);
title.addEventListener(`click`, toggleCallout);
const collapsed = div.classList.contains(`is-collapsed`);
const height = collapsed ? title.scrollHeight : div.scrollHeight;
div.style.maxHeight = height + `px`;
}
}
}
document.addEventListener(`nav`, setupCallout);
window.addEventListener(`resize`, setupCallout);
</script><script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
const darkMode = document.documentElement.getAttribute('saved-theme') === 'dark'
mermaid.initialize({
startOnLoad: false,
securityLevel: 'loose',
theme: darkMode ? 'dark' : 'default'
});
document.addEventListener('nav', async () => {
await mermaid.run({
querySelector: '.mermaid'
})
});
</script><script src="https://cdn.jsdelivr.net/npm/katex@0.16.7/dist/contrib/copy-tex.min.js" type="application/javascript"></script><script src="../../../postscript.js" type="module"></script></html>
Copy Permalink