评论

技术文章写作规范

一篇好的文章不仅要内容好,表达清晰、界面好看也是很重要的。这里分享一些阮一峰老师写的中文技术文档的部分内容,希望对大家有帮助。

技术文章写作规范

来源: GitHub - ruanyf/document-style-guide: 中文技术文档的写作规范,by阮一峰

前言

最近在写文章会想一篇好的文章是不是和写语文作文一样有规范呢?所以就在网上看到阮一峰老师的写的这篇中文技术文档写作规范,觉得真的写得很好,这里就和大家分享一下。

但是阮老师写的是技术文档规范,个人觉得文章的话如果整得太严肃的话或许不太好,不过一些结构,表达还是要注意得,像代码用 md 代码块, uml 图等等会好一点,当然这是个人爱好,这里给大家转载一些我觉得在平时写文章要注意一下的几个点,有兴趣的可以直接去看阮老师的正文!

标题

层级

标题分为四级。

  • 一级标题:文章的标题
  • 二级标题:文章主要部分的大标题
  • 三级标题:二级标题下面一级的小标题
  • 四级标题:三级标题下面某一方面的小标题

下面是示例。

# 一级标题

## 二级标题

### 三级标题

#### 四级标题

原则

(1)一级标题下,不能直接出现三级标题。

示例:下面的文章结构,缺少二级标题。

# 一级标题

### 三级标题

(2)标题要避免孤立编号(即同级标题只有一个)。

示例:下面的文章结构,二级标题 A只包含一个三级标题,完全可以省略三级标题 A

## 二级标题 A

### 三级标题 A

## 二级标题 B

(3)下级标题不重复上一级标题的名字。

示例:下面的文章结构,二级标题与下属的三级标题同名,建议避免。

## 概述

### 概述

(4)谨慎使用四级标题,尽量避免出现,保持层级的简单,防止出现过于复杂的章节。

如果三级标题下有并列性的内容,建议只使用项目列表(Item list)。

示例:下面的结构二要好于结构一。结构一适用的场景,主要是较长篇幅的内容。

结构一

### 三级标题

#### 四级标题 A

#### 四级标题 B

#### 四级标题 C

结构二

### 三级标题

**(1)A**

**(2)B**

**(3)C**

文本

字间距

(1)全角中文字符与半角英文字符之间,应有一个半角空格。

错误:本文介绍如何快速启动Windows系统。

正确:本文介绍如何快速启动 Windows 系统。

(2)全角中文字符与半角阿拉伯数字之间,有没有半角空格都可,但必须保证风格统一,不能两种风格混杂。

正确:2011515日,我订购了5台笔记本电脑与10台平板电脑。

正确:2011515 日,我订购了 5 台笔记本电脑与 10 台平板电脑。

半角的百分号,视同阿拉伯数字。

正确:今年我国经济增长率是6.5%。

正确:今年我国经济增长率是 6.5%。

(3)英文单位若不翻译,单位前的阿拉伯数字与单位符号之间,应留出适当的空隙。

1:一部容量为 16 GB 的智能手机

例21 h = 60 min = 3,600 s

(4)半角英文字符和半角阿拉伯数字,与全角标点符号之间不留空格。

错误:他的电脑是 MacBook Air 。

正确:他的电脑是 MacBook Air。

句子

(1)避免使用长句。

不包含任何标点符号的单个句子,或者以逗号分隔的句子构件,长度尽量保持在 20 个字以内;20~29 个字的句子,可以接受;30~39 个字的句子,语义必须明确,才能接受;多于 40 个字的句子,任何情况下都不能接受。

错误:本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。

正确:本产品适用于多种体系结构。无论是由一台服务器(单一节点结构),还是由多台服务器(并行处理结构)进行动作控制,均可以使用本产品。

逗号分割的长句,总长度不应该超过 100 字或者正文的 3 行。

(2)尽量使用简单句和并列句,避免使用复合句。

并列句:他昨天生病了,没有参加会议。

复合句:那个昨天生病的人没有参加会议。

(3)同样一个意思,尽量使用肯定句表达,不使用否定句表达。

错误:请确认没有接通装置的电源。

正确:请确认装置的电源已关闭。

(4)避免使用双重否定句。

错误:没有删除权限的用户,不能删除此文件。

正确:用户必须拥有删除权限,才能删除此文件。

变化程度的表示法

数字的增加要使用“增加了”、“增加到”。“了”表示增量,“到”表示定量。

增加到过去的两倍
(过去为一,现在为二)

增加了两倍
(过去为一,现在为三)

数字的减少要使用“降低了”、“降低到”。“了”表示增量,“到”表示定量。

降低到百分之八十
(定额是一百,现在是八十)

降低了百分之八十
(原来是一百,现在是二十)

不能用“降低 N 倍”或“减少 N 倍”的表示法,要用“降低百分之几”或“减少百分之几”。因为减少(或降低)一倍表示数值原来为一百,现在等于零。

参考链接

最后一次编辑于  2021-11-18  
点赞 8
收藏
评论

6 个评论

  • Smooth
    Smooth
    2021-11-18

    总结得挺详细,但感觉开放社区这里发表文章的markdown编辑器多少还是跟电脑上下载的Markdown软件有不同,比如说代码块下方会将下一行文字给吸上来,视觉上不美观,却无法用<br/>的换行键将吸附在一起的给隔开(br用不了)

    2021-11-18
    赞同 3
    回复 1
    • ...
      ...
      2021-11-18
      对啊,这个确实,挤在一块了
      2021-11-18
      回复
  • build up
    build up
    2021-11-18

    学习到了很多,感谢分享~

    2021-11-18
    赞同 2
    回复
  • 谋谋谋
    谋谋谋
    2021-11-18

    学到了学到了 社区大佬真多

    2021-11-18
    赞同 2
    回复 1
    • ...
      ...
      2021-11-18
      一起学习!
      2021-11-18
      回复
  • PD
    PD
    发表于移动端
    2021-11-19
    写作规范可以增加可读性,谢谢分享
    2021-11-19
    赞同 1
    回复
  • 微喵网络
    微喵网络
    2021-11-18

    阮一峰真是宝藏大佬

    2021-11-18
    赞同 1
    回复 1
    • ...
      ...
      2021-11-18
      对呀,他的教程真的是浅显易懂,很适合入门的同学看
      2021-11-18
      回复
  • Candy
    Candy
    2021-11-18

    最近也在研究技术文章写作,感谢分享哈哈

    2021-11-18
    赞同 1
    回复 1
    • ...
      ...
      2021-11-18
      哈哈哈一起学习!
      2021-11-18
      回复
登录 后发表内容