From 6d0f6fc8eaa902d05f568763a68e9a0bd733cf1d Mon Sep 17 00:00:00 2001 From: yikeke Date: Thu, 15 Oct 2020 14:12:24 +0800 Subject: [PATCH 1/3] Add a new guideline about adding external link hint --- ...344\272\216\346\234\254\346\214\207\345\215\227.md" | 8 ++++---- ...346\243\200\346\237\245\345\267\245\345\205\267.md" | 10 +++++----- .../\350\257\255\346\263\225.md" | 4 ++-- .../\351\223\276\346\216\245.md" | 8 +++++++- ...347\224\250\350\257\215\346\201\260\345\275\223.md" | 2 +- 5 files changed, 19 insertions(+), 13 deletions(-) diff --git "a/source/\345\205\263\344\272\216\346\234\254\346\214\207\345\215\227.md" "b/source/\345\205\263\344\272\216\346\234\254\346\214\207\345\215\227.md" index 2356756c..274716f4 100644 --- "a/source/\345\205\263\344\272\216\346\234\254\346\214\207\345\215\227.md" +++ "b/source/\345\205\263\344\272\216\346\234\254\346\214\207\345\215\227.md" @@ -6,7 +6,7 @@ > > - 本指南只提供参考规范，不提供权威标准。一些规范在业界并无定论，有争议的点作者会以建议形式给出。 > - 本指南欢迎所有业界同仁们贡献、讨论、改编。 -> - 本指南保持更新，欢迎任何人提出改进意见，如发现有错误或遗漏的点，请提 [Issue](https://github.com/yikeke/zh-style-guide/issues/new)。 +> - 本指南保持更新，欢迎任何人提出改进意见，如发现有错误或遗漏的点，请提 [Issue](https://github.com/yikeke/zh-style-guide/issues/new "点击前往 GitHub")。 希望本指南的出现能为日后业界标准的建立贡献一点力量。 @@ -28,7 +28,7 @@ ## 用词说明 -本指南使用的表示“要求”的全部关键词已在下表第二列列出，具体释义请参见 [RFC2119](https://tools.ietf.org/html/rfc2119) 对相应词语做出的相关规定： +本指南使用的表示“要求”的全部关键词已在下表第二列列出，具体释义请参见 [RFC2119](https://tools.ietf.org/html/rfc2119 "点击前往外部站点") 对相应词语做出的相关规定： | RFC2119 中定义的关键词 | 对应的中文关键词 | 释义说明 | | -------------------------- | --------------------------- | ------------------------------------------------------------ | @@ -44,11 +44,11 @@ 此列表汇总了本指南的所有贡献者名单。 -欢迎在 GitHub 上[提交 Pull Request](https://github.com/yikeke/zh-style-guide) 进行贡献。 +欢迎在 GitHub 上[提交 Pull Request](https://github.com/yikeke/zh-style-guide "点击前往 GitHub") 进行贡献。 | 贡献者 | 总提交贡献数 | First Commit | | ----------- | ------------------ | ------------------ | | yikeke | 37 | 2020-09-14 | | CharLotteiu | 12 | 2020-09-14 | -> 数据来源：[yikeke/zh-style-guide - Contributor Graph](https://github.com/yikeke/zh-style-guide/graphs/contributors)。 +> 数据来源：[yikeke/zh-style-guide - Contributor Graph](https://github.com/yikeke/zh-style-guide/graphs/contributors "点击前往 GitHub")。 diff --git "a/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\346\226\207\346\241\243\350\264\250\351\207\217\346\243\200\346\237\245\345\267\245\345\205\267.md" "b/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\346\226\207\346\241\243\350\264\250\351\207\217\346\243\200\346\237\245\345\267\245\345\205\267.md" index 559314b1..a872ec78 100644 --- "a/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\346\226\207\346\241\243\350\264\250\351\207\217\346\243\200\346\237\245\345\267\245\345\205\267.md" +++ "b/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\346\226\207\346\241\243\350\264\250\351\207\217\346\243\200\346\237\245\345\267\245\345\205\267.md" @@ -2,9 +2,9 @@ 一名成熟的文档工程师应该配置自己的文档编辑器，保证其能对文档自动进行拼写和语法检查。推荐以下几种对文档自动进行质量检查的工具。 -- [Grammarly](https://www.grammarly.com/grammar-check) +- [Grammarly](https://www.grammarly.com/grammar-check "点击前往外部站点") - Visual Studio Code 插件 - - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - - [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) -- [LanguageTool](https://languagetool.org/) -- [Vale](https://github.com/errata-ai/vale) + - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker "点击前往外部站点") + - [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint "点击前往外部站点") +- [LanguageTool](https://languagetool.org/ "点击前往外部站点") +- [Vale](https://github.com/errata-ai/vale "点击前往外部站点") diff --git "a/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\350\257\255\346\263\225.md" "b/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\350\257\255\346\263\225.md" index 5774731e..6d3ec4ab 100644 --- "a/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\350\257\255\346\263\225.md" +++ "b/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\350\257\255\346\263\225.md" @@ -40,11 +40,11 @@ ### 成分多余 -【示例一】根据官方建议，目前稳定版本的 HAProxy 为稳定版 [2.0 特性](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/)。 +【示例一】根据官方建议，目前稳定版本的 HAProxy 为稳定版 [2.0 特性](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/ "点击前往外部站点")。 【解释】官方目前建议使用 HAProxy 稳定版本 2.0，2.0 特性可以参考此链接。 -【建议】官方目前建议使用 [HAProxy 稳定版本 2.0](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/)。 +【建议】官方目前建议使用 [HAProxy 稳定版本 2.0](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/ "点击前往外部站点")。 ### 句式杂糅 diff --git "a/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" "b/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" index a9b07ad0..5978f99f 100644 --- "a/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" +++ "b/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" @@ -6,7 +6,7 @@ Markdown 中的链接格式示例： - 链至同一文档中的其他标题：`[产品架构](#产品架构)` - 链至其他相邻文档：`[产品架构](../docs/architecture.md)` -- 链至外部站点：`[贡献者指南](https://docs.microsoft.com/zh-cn/contribute/)` +- 链至外部站点：`[贡献者指南](https://docs.microsoft.com/zh-cn/contribute/ "点击前往外部站点")` ### 链接的描述 @@ -37,3 +37,9 @@ Markdown 链接中方括号 () 里的内容即为该链接的路径。链接的 - 链接路径应尽量统一风格。例如，链接至非外部站点时应统一使用相对路径或绝对路径，不建议混用相对路径和绝对路径。 - 建议减少将用户链至外部站点的次数，以免外部站点的页面失效而影响用户体验。 + + > 外部站点的含义：A 网站的文档中出现了一个 B 链接，如果 B 与 A 的域名或服务器不一样，则对于 A 网站的文档来说，B 链接为外部站点。例如：cloud.google.com 相对于 support.google.com 为内部站点；cloud.google.com 相对于 kubernetes.io 为外部站点。 + +- **如果必须将用户链至外部站点，建议在链接的路径后加上明显的标示，提醒用户该链接前往外部站点。**在 Markdown 中，可以简单在链接的路径后加上 `"点击前往外部站点"` 或者 `"点击前往 XXX 网站"`等信息，如 `[链接的描述](链接的路径 "前往外部链接的提示")`，即可在正常渲染下，实现鼠标悬停在超链接上时出现提示的效果。 + + > 由于不同网站的使用条款和隐私政策不同，用户使用当前站点，一般默认用户已经接受了当前站点的法律条文。跳出当前站点之前，网站维护者有责任提醒用户当前的链接是去往外部站点，跳出去之后如果用户发生问题，不是当前站点的责任。 diff --git "a/source/\350\257\255\350\250\200\351\243\216\346\240\274/\347\224\250\350\257\215\346\201\260\345\275\223.md" "b/source/\350\257\255\350\250\200\351\243\216\346\240\274/\347\224\250\350\257\215\346\201\260\345\275\223.md" index c1e96191..5e6adf5f 100644 --- "a/source/\350\257\255\350\250\200\351\243\216\346\240\274/\347\224\250\350\257\215\346\201\260\345\275\223.md" +++ "b/source/\350\257\255\350\250\200\351\243\216\346\240\274/\347\224\250\350\257\215\346\201\260\345\275\223.md" @@ -4,7 +4,7 @@ ### 禁用词 -用词正确体现在不使用有冒犯性的禁用词语。技术文档中的禁用词可参考[新华社 2015 年 11 月发布的《新华社新闻报道中的禁用词（第一批）》](https://www.digitaling.com/articles/22975.html)。技术文档虽不是新闻报道，但作为技术传播领域的大众传播物，应当同样考虑文档传播带来的影响。避免使用具有冒犯性的词语，能为个人或公司节省不必要的麻烦。 +用词正确体现在不使用有冒犯性的禁用词语。技术文档中的禁用词可参考[新华社 2015 年 11 月发布的《新华社新闻报道中的禁用词（第一批）》](https://www.digitaling.com/articles/22975.html "点击前往外部站点")。技术文档虽不是新闻报道，但作为技术传播领域的大众传播物，应当同样考虑文档传播带来的影响。避免使用具有冒犯性的词语，能为个人或公司节省不必要的麻烦。 以下是《新华社新闻报道中的禁用词（第一批）》中比较适用于技术文档的几点： From 489d9639311dbbdb90059a96470a1bb390e9ee15 Mon Sep 17 00:00:00 2001 From: yikeke Date: Fri, 16 Oct 2020 13:43:50 +0800 Subject: [PATCH 2/3] Revert "Add a new guideline about adding external link hint" This reverts commit 6d0f6fc8eaa902d05f568763a68e9a0bd733cf1d. --- ...344\272\216\346\234\254\346\214\207\345\215\227.md" | 8 ++++---- ...346\243\200\346\237\245\345\267\245\345\205\267.md" | 10 +++++----- .../\350\257\255\346\263\225.md" | 4 ++-- .../\351\223\276\346\216\245.md" | 8 +------- ...347\224\250\350\257\215\346\201\260\345\275\223.md" | 2 +- 5 files changed, 13 insertions(+), 19 deletions(-) diff --git "a/source/\345\205\263\344\272\216\346\234\254\346\214\207\345\215\227.md" "b/source/\345\205\263\344\272\216\346\234\254\346\214\207\345\215\227.md" index 274716f4..2356756c 100644 --- "a/source/\345\205\263\344\272\216\346\234\254\346\214\207\345\215\227.md" +++ "b/source/\345\205\263\344\272\216\346\234\254\346\214\207\345\215\227.md" @@ -6,7 +6,7 @@ > > - 本指南只提供参考规范，不提供权威标准。一些规范在业界并无定论，有争议的点作者会以建议形式给出。 > - 本指南欢迎所有业界同仁们贡献、讨论、改编。 -> - 本指南保持更新，欢迎任何人提出改进意见，如发现有错误或遗漏的点，请提 [Issue](https://github.com/yikeke/zh-style-guide/issues/new "点击前往 GitHub")。 +> - 本指南保持更新，欢迎任何人提出改进意见，如发现有错误或遗漏的点，请提 [Issue](https://github.com/yikeke/zh-style-guide/issues/new)。 希望本指南的出现能为日后业界标准的建立贡献一点力量。 @@ -28,7 +28,7 @@ ## 用词说明 -本指南使用的表示“要求”的全部关键词已在下表第二列列出，具体释义请参见 [RFC2119](https://tools.ietf.org/html/rfc2119 "点击前往外部站点") 对相应词语做出的相关规定： +本指南使用的表示“要求”的全部关键词已在下表第二列列出，具体释义请参见 [RFC2119](https://tools.ietf.org/html/rfc2119) 对相应词语做出的相关规定： | RFC2119 中定义的关键词 | 对应的中文关键词 | 释义说明 | | -------------------------- | --------------------------- | ------------------------------------------------------------ | @@ -44,11 +44,11 @@ 此列表汇总了本指南的所有贡献者名单。 -欢迎在 GitHub 上[提交 Pull Request](https://github.com/yikeke/zh-style-guide "点击前往 GitHub") 进行贡献。 +欢迎在 GitHub 上[提交 Pull Request](https://github.com/yikeke/zh-style-guide) 进行贡献。 | 贡献者 | 总提交贡献数 | First Commit | | ----------- | ------------------ | ------------------ | | yikeke | 37 | 2020-09-14 | | CharLotteiu | 12 | 2020-09-14 | -> 数据来源：[yikeke/zh-style-guide - Contributor Graph](https://github.com/yikeke/zh-style-guide/graphs/contributors "点击前往 GitHub")。 +> 数据来源：[yikeke/zh-style-guide - Contributor Graph](https://github.com/yikeke/zh-style-guide/graphs/contributors)。 diff --git "a/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\346\226\207\346\241\243\350\264\250\351\207\217\346\243\200\346\237\245\345\267\245\345\205\267.md" "b/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\346\226\207\346\241\243\350\264\250\351\207\217\346\243\200\346\237\245\345\267\245\345\205\267.md" index a872ec78..559314b1 100644 --- "a/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\346\226\207\346\241\243\350\264\250\351\207\217\346\243\200\346\237\245\345\267\245\345\205\267.md" +++ "b/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\346\226\207\346\241\243\350\264\250\351\207\217\346\243\200\346\237\245\345\267\245\345\205\267.md" @@ -2,9 +2,9 @@ 一名成熟的文档工程师应该配置自己的文档编辑器，保证其能对文档自动进行拼写和语法检查。推荐以下几种对文档自动进行质量检查的工具。 -- [Grammarly](https://www.grammarly.com/grammar-check "点击前往外部站点") +- [Grammarly](https://www.grammarly.com/grammar-check) - Visual Studio Code 插件 - - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker "点击前往外部站点") - - [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint "点击前往外部站点") -- [LanguageTool](https://languagetool.org/ "点击前往外部站点") -- [Vale](https://github.com/errata-ai/vale "点击前往外部站点") + - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) + - [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +- [LanguageTool](https://languagetool.org/) +- [Vale](https://github.com/errata-ai/vale) diff --git "a/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\350\257\255\346\263\225.md" "b/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\350\257\255\346\263\225.md" index 6d3ec4ab..5774731e 100644 --- "a/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\350\257\255\346\263\225.md" +++ "b/source/\346\213\274\345\206\231\344\270\216\350\257\255\346\263\225/\350\257\255\346\263\225.md" @@ -40,11 +40,11 @@ ### 成分多余 -【示例一】根据官方建议，目前稳定版本的 HAProxy 为稳定版 [2.0 特性](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/ "点击前往外部站点")。 +【示例一】根据官方建议，目前稳定版本的 HAProxy 为稳定版 [2.0 特性](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/)。 【解释】官方目前建议使用 HAProxy 稳定版本 2.0，2.0 特性可以参考此链接。 -【建议】官方目前建议使用 [HAProxy 稳定版本 2.0](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/ "点击前往外部站点")。 +【建议】官方目前建议使用 [HAProxy 稳定版本 2.0](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/)。 ### 句式杂糅 diff --git "a/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" "b/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" index 5978f99f..a9b07ad0 100644 --- "a/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" +++ "b/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" @@ -6,7 +6,7 @@ Markdown 中的链接格式示例： - 链至同一文档中的其他标题：`[产品架构](#产品架构)` - 链至其他相邻文档：`[产品架构](../docs/architecture.md)` -- 链至外部站点：`[贡献者指南](https://docs.microsoft.com/zh-cn/contribute/ "点击前往外部站点")` +- 链至外部站点：`[贡献者指南](https://docs.microsoft.com/zh-cn/contribute/)` ### 链接的描述 @@ -37,9 +37,3 @@ Markdown 链接中方括号 () 里的内容即为该链接的路径。链接的 - 链接路径应尽量统一风格。例如，链接至非外部站点时应统一使用相对路径或绝对路径，不建议混用相对路径和绝对路径。 - 建议减少将用户链至外部站点的次数，以免外部站点的页面失效而影响用户体验。 - - > 外部站点的含义：A 网站的文档中出现了一个 B 链接，如果 B 与 A 的域名或服务器不一样，则对于 A 网站的文档来说，B 链接为外部站点。例如：cloud.google.com 相对于 support.google.com 为内部站点；cloud.google.com 相对于 kubernetes.io 为外部站点。 - -- **如果必须将用户链至外部站点，建议在链接的路径后加上明显的标示，提醒用户该链接前往外部站点。**在 Markdown 中，可以简单在链接的路径后加上 `"点击前往外部站点"` 或者 `"点击前往 XXX 网站"`等信息，如 `[链接的描述](链接的路径 "前往外部链接的提示")`，即可在正常渲染下，实现鼠标悬停在超链接上时出现提示的效果。 - - > 由于不同网站的使用条款和隐私政策不同，用户使用当前站点，一般默认用户已经接受了当前站点的法律条文。跳出当前站点之前，网站维护者有责任提醒用户当前的链接是去往外部站点，跳出去之后如果用户发生问题，不是当前站点的责任。 diff --git "a/source/\350\257\255\350\250\200\351\243\216\346\240\274/\347\224\250\350\257\215\346\201\260\345\275\223.md" "b/source/\350\257\255\350\250\200\351\243\216\346\240\274/\347\224\250\350\257\215\346\201\260\345\275\223.md" index 5e6adf5f..c1e96191 100644 --- "a/source/\350\257\255\350\250\200\351\243\216\346\240\274/\347\224\250\350\257\215\346\201\260\345\275\223.md" +++ "b/source/\350\257\255\350\250\200\351\243\216\346\240\274/\347\224\250\350\257\215\346\201\260\345\275\223.md" @@ -4,7 +4,7 @@ ### 禁用词 -用词正确体现在不使用有冒犯性的禁用词语。技术文档中的禁用词可参考[新华社 2015 年 11 月发布的《新华社新闻报道中的禁用词（第一批）》](https://www.digitaling.com/articles/22975.html "点击前往外部站点")。技术文档虽不是新闻报道，但作为技术传播领域的大众传播物，应当同样考虑文档传播带来的影响。避免使用具有冒犯性的词语，能为个人或公司节省不必要的麻烦。 +用词正确体现在不使用有冒犯性的禁用词语。技术文档中的禁用词可参考[新华社 2015 年 11 月发布的《新华社新闻报道中的禁用词（第一批）》](https://www.digitaling.com/articles/22975.html)。技术文档虽不是新闻报道，但作为技术传播领域的大众传播物，应当同样考虑文档传播带来的影响。避免使用具有冒犯性的词语，能为个人或公司节省不必要的麻烦。 以下是《新华社新闻报道中的禁用词（第一批）》中比较适用于技术文档的几点： From d7f9a18d904f51410a00107b85004bf144300edd Mon Sep 17 00:00:00 2001 From: yikeke Date: Fri, 16 Oct 2020 13:52:42 +0800 Subject: [PATCH 3/3] update external link icon guideline --- .../\351\223\276\346\216\245.md" | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git "a/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" "b/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" index a9b07ad0..edca2c9e 100644 --- "a/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" +++ "b/source/\346\226\207\346\241\243\345\206\205\345\256\271\345\205\203\347\264\240/\351\223\276\346\216\245.md" @@ -37,3 +37,13 @@ Markdown 链接中方括号 () 里的内容即为该链接的路径。链接的 - 链接路径应尽量统一风格。例如，链接至非外部站点时应统一使用相对路径或绝对路径，不建议混用相对路径和绝对路径。 - 建议减少将用户链至外部站点的次数，以免外部站点的页面失效而影响用户体验。 + + > 外部站点的含义：A 网站的文档中出现了一个 B 链接，如果 B 与 A 的域名或服务器不一样，则对于 A 网站的文档来说，B 链接为外部站点。例如：cloud.google.com 相对于 support.google.com 为内部站点；cloud.google.com 相对于 kubernetes.io 为外部站点。 + +- **如果必须将用户链至外部站点，建议在该外链后加上明显的标示，提醒用户该链接将前往外部站点。** + + > 由于不同网站的使用条款和隐私政策不同，用户使用当前站点，一般默认用户已经接受了当前站点的法律条文。跳出当前站点之前，网站维护者有责任提醒用户当前的链接是去往外部站点，跳出去之后如果用户发生问题，不是当前站点的责任。 + + - 【示例一】如果前端能力足够，可以在外链后加上通用的外链 icon 效果，比如：[贡献者名单](https://github.com/yikeke/zh-style-guide/graphs/contributors)。 + + - 【示例二】在 Markdown 中，可以简单在链接的路径后加上 `"点击前往外部站点"` 或者 `"点击前往 XXX 网站"`等信息，如 `[链接的描述](链接的路径 "前往外部链接的提示")`，即可在正常渲染下，实现鼠标悬停在超链接上时出现提示的效果。