Markdown技术文档编写规范

Markdown技术文档编写规范

Logo

Markdown是一种可以使用普通文本编辑器编写的标记语言,通过简单的标记语法,它可以使普通文本内容具有一定的格式。


文档体系

  • 结构

    • 简介(Introduction): [必备] [文件] 提供对产品和文档本身的总体的、扼要的说明

    • 快速上手(Getting Started):[可选] [文件] 如何最快速地使用产品

    • 入门篇(Basics): [必备] [目录] 又称”使用篇“,提供初级的使用教程

      • 环境准备(Prerequisite):[必备] [文件] 软件使用需要满足的前置条件
      • 安装(Installation):[可选] [文件] 软件的安装方法
      • 设置(Configuration):[必备] [文件] 软件的设置
    • 进阶篇(Advanced):[可选] [目录] 又称”开发篇“,提供中高级的开发教程

    • API(Reference):[可选] [目录|文件] 软件 API 的逐一介绍

    • FAQ:[可选] [文件] 常见问题解答

    • 附录(Appendix):[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容

      • Glossary:[可选] [文件] 名词解释
      • Recipes:[可选] [文件] 最佳实践
      • Troubleshooting:[可选] [文件] 故障处理
      • ChangeLog:[可选] [文件] 版本说明
      • Feedback:[可选] [文件] 反馈方式

规则

  • Markdown文档文件后缀名使用 .md

  • 文件名建议只使用小写字母,多个单词可使用 - 分隔。

    • 文件名不得含有空格。
    • 文件名不得使用全角字符(中文不能用于文件名)。
    • (为了醒目,某些说明文件的文件名,可以使用大写字母,例如 README.md LICENSE.md文件。)
  • 文件编码统一使用 UTF-8

  • 文章标题与内容之间必须有一个空行。

    // false
    ## 章节一
    内容
    ## 章节二
    
    // true
    ## 章节一
    
    内容
    
    ##章节二
    
  • 代码段必须使用如下风格:

···
// some code
// this is FCB(Fenced code blocks Style)
···
  • 表格写法应该参考如下风格:
First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ |:---------------:| -----:|
| col 3 is      | some wordy text | $1600 |
| col 2 is      | centered        |   $12 |
| zebra stripes | are neat        |    $1 |
  • 中英文混排应该采用以下规则:

    • 英文和数字应使用半角字符
    • 中文文字之间不加空格
    • 中文文字与英文、阿拉伯数字及 @ # $ % ^ & * . ( ) 等符号之间加空格
    • 中文标点之间不加空格
    • 中文标点与前后字符(无论全角或半角)之间不加空格
    • 如果括号内有中文,则使用中文括号
    • 如果括号中的内容全部都是英文,则使用半角英文括号
    • 当半角符号 / 表示「或者」之意时,与前后的字符之间均不加空格
  • 中文符号应该使用如下写法

    • 用直角引号(「」)代替双引号(“”)
    • 省略号使用「……」,而「。。。」仅用于表示停顿
  • 表达方式(语法规范):

    • 使段落成为文章的单元:一个段落只表达一个主题
    • 通常在每一段落开始要点题,在段落结尾要扣题
    • 使用主动语态
    • 陈述句中使用肯定说法
    • 删除不必要的词
    • 避免连续使用松散的句子
    • 使用相同的结构表达并列的意思
    • 将相关的词放在一起
    • 在总结中,要用同一种时态(这里指英文中的时态,中文不适用,所以可以不理会)
    • 将强调的词放在句末

你可能感兴趣的:(Markdown技术文档编写规范)