Skip to content

Commit 02fd535

Browse files
authored
feat: add docs wirte guide (#159)
* feat: add docs wirte guide
1 parent 0e9ed87 commit 02fd535

File tree

1 file changed

+72
-0
lines changed

1 file changed

+72
-0
lines changed

open-source-write-guide.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
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. 文章完成之后,**自己阅读一下,避免出现错误问题!**

0 commit comments

Comments
 (0)