中文技术文档写作规范(汇总整理版)

前言:规范文档的好处,其一增加文档易读性,其二体现个人专业性

  • 只使用一二三级标题,三级标题下面的并列性内容使用列表展示
  • 二级标题前使用行分隔符表示分隔
  • 段落之间使用一个空行隔开
  • 一句话或者以逗号分隔的句子,长度尽量保持在 20 个字以内,20~29 个字的句子,可以接受
  • 禁止文字口语化
  • 尽量使用肯定句表达,不使用否定句表达(例如:没有、不能、不可以)
  • 不使用“被”
  • 技术名词大小写拼写正确,比如正确的拼写:Java、JavaScript、MySQL
  • 第一次出现英文词汇时,在括号中给出中文标注【例如:IOC(International Olympic Committee,国际奥林匹克委员会)】
  • 引号里面还要用引号时,外面一层用双引号,里面一层用单引号
  • 句子末尾用括号加注释时,句号应在括号后面(例如)。
  • 中文字符和英文、数字之间保持一个空格,其他符号无需空格
  • 数字和英文单位之间保留一个空格(如 10 kg)
  • 对于四位以上的数值,应添加千分号(如 1,200,000 元)
  • 数值范围(例如日期、时间或数字)应该使用波浪连接号(~)或一字号(—),波浪连接号前后两个值都建议加上单位(如 10 kg~20 kg 或者中文格式 -20 °C 至 -10 °C)
  • 使用外部图片时,必须在图片下方标明来源(例如:图片来源 CSDN | PANDA)
  • 引用第三方内容时,应在文末标明,并链接至原文
  • 文件名尽量只使用英文小写,不得使用大写字母,除非是某些说明文件,比如 README.md

参考链接

中文技术文档的写作规范 | 阮一峰

你可能感兴趣的:(JAVA,经验分享,代码规范)