File tree Expand file tree Collapse file tree 1 file changed +72
-0
lines changed Expand file tree Collapse file tree 1 file changed +72
-0
lines changed Original file line number Diff line number Diff line change 1+ # 为什么要写本篇文章
2+
3+ 写作本篇文章的目的是:在编写和开源实践有关的文档内容时,遵守此文档写作规范。以便初次参与开源的人能够更好的理解文章描述内容,找到自己的方向。
4+
5+ ## 写作指南
6+
7+ > 文档编写可以参考:https://github.com/ruanyf/document-style-guide
8+
9+ 1 . 注意文章写作格式,一些 Markdown 的语法等,灵活使用,使文章内容更具有条理性和可读性;
10+
11+ 2 . 使用正确的标点符号(中英文符号);
12+
13+ ``` markdown
14+ 例如一句话结尾时:
15+
16+ 错误:今天太阳很好.
17+
18+ 正确:今天太阳很好。
19+ ```
20+
21+ 3 . 注意专有名词的书写(英文文档注意词性);
22+
23+ ``` markdown
24+ 错误:我们将会使用 spring cloud openfeign 完成服务调用。
25+
26+ 正确:我们将会使用 Spring Cloud OpenFeign 完成服务调用。
27+ ```
28+
29+ 4 . 避免出现缩写内容(或者文章第一次出现时说明);
30+
31+ ``` markdown
32+ 错误:下文中,将使用 SCA 的服务治理能力。
33+
34+ 正确:
35+ 1. 下文中,将使用 Spring Cloud Alibaba 的服务治理能力。
36+ 2. 使用 Spring Cloud Alibaba(后文简称SCA)声明
37+
38+ 5. 使用 Markdown 时为不同的代码块指定对应的语言;
39+
40+ 1. 错误
41+
42+ ```xml
43+ {
44+ "user": "zhangsan",
45+ "age": "12"
46+ }
47+ ```
48+
49+ 2. 正确
50+
51+ ```json
52+ {
53+ "user": "zhangsan",
54+ "age": "12"
55+ }
56+ ```
57+
58+ 6. 对文章中一些专有名词提供链接;
59+
60+ ```markdown
61+ 错误:下文中将使用 Github Action 来完成 CI/CD。
62+
63+ 正确:下文中将使用 [Github Action](https://docs.github.com/zh/actions) 来完成 [CI/CD](https://www.redhat.com/en/topics/devops/what-is-ci-cd)。
64+ ```
65+
66+ 7 . 对重点内容使用加粗,下划线等着重强调;
67+
68+ 8 . 明确文章的受众群体,站在受众群体思考,确保对当前受众群体而言,有一定的参考价值。
69+
70+ 9 . 使用合适的人称代词;
71+
72+ 10 . 文章完成之后,** 自己阅读一下,避免出现错误问题!**
You can’t perform that action at this time.
0 commit comments