1、技术文档写作规范(Markdown)
标题分为四级。
下面是示例。
（1）一级标题下，不能直接出现三级标题。
示例：下面的文章结构，缺少二级标题。
（2）标题要避免孤立编号（即同级标题只有一个）。
示例：下面的文章结构， 二级标题 A 只包含一个三级标题，完全可以省略 三级标题 A 。
（3）下级标题不重复上一级标题的名字。
示例：下面的文章结构，二级标题与下属的三级标题同名，建议避免。
（4）谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节。
如果三级标题下有并列性的内容，建议只使用项目列表（Item list）。
示例：下面的结构二要好于结构一。后者适用的场景，主要是较长篇幅的内容。
全角中文字符与半角英文字符之间，应有一个半角空格。
全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。
半角的百分号，视同阿拉伯数字。
英文单位若不翻译，单位前的阿拉伯数字与单位间不留空格。
半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。
1、尽量不使用被动语态，改为使用主动语态。
2、不使用非正式的语言风格。
3、不使用冷僻、生造或者文言文的词语，而要使用现代汉语的常用表达方式。
4、用对“的”、“地”、“得”。
5、使用代词时（比如“其”、“该”、“此”、“这”等词），必须明确指代的内容，保证只有一个含义。
6、名词前不要使用过多的形容词。
7、不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，在任何情况下都不能接受。
8、同样一个意思，尽量使用肯定句表达，不使用否定句表达。
9、避免使用双重否定句。
英文原文如果使用了复数形式，翻译成中文时，应该将其还原为单数形式。
外文缩写可以使用半角圆点( . )表示缩写。
表示中文时，英文省略号（ ⋯ ）应改为中文省略号（ …… ）。
英文书名或电影名改用中文表达时，双引号应改为书名号。
第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。
专有名词中每个词第一个字母均应大写，非专有名词则不需要大写。
引用第三方内容时，应注明出处。
使用外部图片时，必须在图片下方或文末标明来源。
数字一律使用半角形式，不得使用全角形式。
数值为千位以上，应添加千分号（半角逗号）。
对于 4 ～ 6 位的数值，千分号是选用的，比如 1000 和 1,000 都可以接受。对于7位及以上的数值，千分号是必须的。
多位小数要从小数点后从左向右添加千分号，比如 4.234,345 。
货币应为阿拉伯数字，并在数字前写出货币符号，或在数字后写出货币中文名称。
表示数值范围时，用 ～ 连接。参见《标点符号》一节的“连接号”部分。
带有单位或百分号时，两个数字都要加上单位或百分号，不能只加后面一个。
数字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。
数字的减少要使用“降低了”、“降低到”。“了”表示增量，“到”表示定量。
不能用“降低N倍”或“减少N倍”的表示法，要用“降低百分之几”或“减少百分之几”。因为减少（或降低）一倍表示数值原来为一百，现在等于零。
中文语句中的结尾处应该用全角句号（ 。 ）。
句子末尾用括号加注时，句号应在括号之外。
逗号 ， 表示句子内部的一般性停顿。
注意避免“一逗到底”，即整个段落除了结尾，全部停顿都使用逗号。
句子内部的并列词，应该用全角顿号( 、 ) 分隔，而不用逗号，即使并列词是英语也是如此。
英文句子中，并列词语之间使用半角逗号（ , ）分隔。
分号 ； 表示复句内部并列分句之间的停顿。
引用时，应该使用全角双引号（ “ ” ），注意前后双引号不同。
引号里面还要用引号时，外面一层用双引号，里面一层用单引号（ ‘ ’ ），注意前后单引号不同。
补充说明时，使用全角圆括号 （） ，括号前后不加空格。
全角冒号（ ： ）常用在需要解释的词语后边，引出解释和说明。
表示时间时，应使用半角冒号（ : ）。
省略号 …… 表示语句未完、或者语气的不连续。它占两个汉字空间、包含六个省略点，不要使用 。。。 或 ... 等非标准形式。
省略号不应与“等”这个词一起使用。
应该使用平静的语气叙述，尽量避免使用感叹号 ！ 。
不得多个感叹号连用，比如 ！！ 和 !!! 。
破折号 ———— 一般用于进一步解释。
破折号应占两个汉字的位置。如果破折号本身只占一个汉字的位置，那么前后应该留出一个半角空格。
连接号用于连接两个类似的词。
以下场合应该使用直线连接号（ - ），占一个半角字符的位置。
以下场合应该使用波浪连接号（ ～ ），占一个全角字符的位置。
注意，波浪连接号前后两个值都应该加上单位。
波浪连接号也可以用汉字“至”代替。
软件手册是一部完整的书，建议采用下面的结构。
下面是两个真实范例，可参考。
文档的文件名不得含有空格。
文件名必须使用半角字符，不得使用全角字符。这也意味着，中文不能用于文件名。
文件名建议只使用小写字母，不使用大写字母。
为了醒目，某些说明文件的文件名，可以使用大写字母，比如 README 、 LICENSE 。
文件名包含多个单词时，单词之间建议使用半角的连词线（ - ）分隔。
查看原文
2、文档工程师的工作内容是什么？
作为一名文档工程师，首先你要了解自己公司产品的性能，完全掌握和理解产品的用途和功能，这样你写出来的文档才能让别人信服。其次，需要掌握的简单技能，比如会使用Dreamweaver，熟练使用办公软件（大多数人都觉得对办公软件很在行，可是能够编辑出自己的模板，熟练写出宏代码之类的才真正算得上能熟练使用）。因为做文档工作很枯燥，所以还需要有一颗稳得住的心。
加油吧，诚恳地面对你的面试官，记得带上微笑，预祝你面试成功。
3、技术写作理论知识- DITA
在早期，技术文档写作方式更其他文档没什么区别，都是线性的写作方式，一般一个产品对应一本文档，随着科技行业的日益发展，技术文档写作需求越来越多，一个产品往往有多个系列，像同一款汽车，有高中低三种配置，他们大部分是相同，只有少部分不同，如果按照线性的写作方式，要写三回，当然有人会说肯定没这么傻，写三回，肯定 and paste，这种方式同样带来问题，就是如果修改会至少要改三个地方，常常容易出错。
针对这种问题，模块化的写作方式应运而生，DITA就是其中的佼佼者。DITA（Darwin Information Typing Architecture）是一种基于XML语言和信息分类的资料开发方法。利用DITA的资料开发方法，可以很好的解决同源和重用问题。
DITA最早有IBM提出，现今已经标准化，具体可以参见 https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
目前市场上用的最多的DITA写作工具就是 Arbortext 了，基于XML语言，写作与样式分离。
使用DITA的方法开发文档的流程一般式这样：
从上图我们可以很直观的看出Topic可以被不同的Map引用，从而做到同源和重用，而Topic不决定发布件的格式，能够做到内容与样式分离。
InfoMapping是一个用于 分析、组织和表达 信息的 原则、技术和标准的集合 。
DITA是一种基于XML的文档开发方法。
个人理解DITA是资料工程方法，是术，InfoMapping是信息理论，是道。两者结合起来，就是技术文档写作的理论基石。
4、技术文档诞生记 | 完整的技术写作流程是怎样的？
如果你有过 Technical Writer 实习或工作经历，那么对技术写作的流程应该已经了解。当然，在很多大公司里，你参与的很可能只是这个流程的某一个环节。例如，你只负责写，或者只负责 review，或者只负责文档架构。相比之下，在创业公司里，可能会参与多个环节。
如果你是尚未毕业而且也没有相关实习经历的在校生，或者已经工作但有意转行做 Technical Writer 的小伙伴，那么可能对技术写作流程仍存疑惑，或者一知半解。
不同公司技术文档流程的划分可能略有差异，但从本质上来看，则大同小异。无论你在这个流程中的哪个环节，从宏观上了解整个流程有助于让你的认识更加清晰，也有助于在有需求时从容地承担其它环节的工作。
这里跟大家分享一个完整的技术文档写作流程，你只需记住六个单词即可。如下图所示：
再说明一下，你从工作中已经了解或即将接触的技术写作流程不一定与上图完全一致，但一个完整的流程一般都会涵盖这些内容，区别多半是主观划分而已，这一点不必拿出“大家来找茬”的精神死磕哦~
准备阶段的工作主要包括以下几点：
在写文档之前，需要明确文档需求。你要了解为什么要写这篇文档，写这篇文档是为了达到什么目的。
也要明确文档受众。受众不同，内容就很可能不同。比如，面向开发人员和非开发人员/普通用户的文档，在内容的组织上就会不同。
还要界定文档范围。思考并确定这篇文档需要覆盖哪些内容或模块，以及不会涉及哪些内容。这样在之后搜集资料的时候就会有所侧重，写的时候也不会模糊不定。
有过技术文档写作经历的小伙伴一定会深有同感，如果不理解某个东西，那么给它写文档简直太痛苦。
那么当遇到一个让你毫无头绪的陌生主题时，该如何尽量避免这种痛苦呢？当然就是尽最大可能去理解了。
可是具体该如何做呢？简言之，即搜集资料。那又该如何搜集资料呢？笔者认为，可以从以下几点着手：
1）对比较有代表性的同类产品或相似产品的相关文档进行调研，看看别人的文档是怎么做的。
在一无所知的时候，借鉴他人的经验做法不失为一种好的选择。通过对几家产品的文档进行对比，你就可以对自己要写的文档建立一个大致的框架。
需要注意的是，借鉴不是照搬，只用于提供思路；产品不同，文档的结构规划也会有差异。
2）采用最有效的方法尽力搜集与所写文档相关的各种资料。
搜集的资料经过 Technical Writer 的摘删组织，很可能就会成为发布文档的一部分。
搜集资料的方法有很多，像网络搜索、调查问卷、访谈、实验，以及邮件讨论、报告、技术文章等等。到底该使用哪种方法要具体分析，需要你根据文档需求、Deadline、已有资料的丰富程度等因素，来选择能快速而准确地搜集到所需资料的方法。
有些主题的写作，通过网络搜索可能几乎无法给你提供任何帮助。即便是这类内容，你也可以从开发人员那里获得一些资料，可以根据自己的需求请他们协助提供资料，抑或是通过内部系统中的开发说明和讨论获取所需信息。
对于软件类的产品文档，即便有了一些技术资料，也往往需要 Technical Writer 自己使用一遍，从而对操作步骤有一个直观的理解，获得文档写作的一手资料。
当资料搜集得差不多的时候就可以组织这篇文档的具体结构了，之前对相似产品的调研或许可以在此时助你一臂之力。
对于常见的产品使用指南，一般按照安装或使用的顺序进行组织；对于其它一些非指南类的文档，也应遵循一定的顺序或逻辑。
此外，还需考虑该文档是否需要配图，是否需要使用表格。如果需要配图，明确是需要他人协助提供，还是需要自己完成。画一个较复杂的图也是一件蛮耗时的事情，花费的时间也需考虑在内。
有了详细的文档架构之后，就可以进行下一步的写作了。
如果做好了前几步的工作，写作将变得非常简单，你只需把相应的内容准确地填到文档架构中。在这个过程中，你需要写一个个段落或者具体的操作步骤。这是一个反映你的语言和写作功底的时刻。
有的 Technical Writing 书籍中说到，在写文档的时候不必在意语法、措辞和标点，认为这些细节应该在 Revision 阶段完善。
我对此有不同的看法。一个合格的 Technical Writer 本身应该有良好的语言功底，像语法、措辞和标点这种最基础的细节本就不该成为一个需要单独解决的问题。规范的语法、得体的措辞、正确的标点应该已经成为一种不需要额外付出精力、也几乎不会占用额外时间的写作习惯。
如果写作的初稿比较粗糙，有许多需要修改的小细节，这必定会增大 review 时的工作量和时间成本，从而延缓文档流程。
或许，对于有精细化分工、每个人只负责一个小环节的大企业，可以采用这种方法。但是，对于快速发展、需要文档敏捷开发的创业公司，这种就不适用了。
写完文档第一稿后，一般都需要进一步修改完善。这里的 Revision 指的是 review 之后的修改，所以这一步也可以叫作： Review & Revision 。
那么需要谁来 review 呢？技术文档通常需要请其他小伙伴进行两种 review，即：
收到 reviewer 的反馈之后，Technical Writer 需要及时作出判断和修改，有不明确的地方需和 reviewer 讨论确定。改完之后，再请 reviewer 看一下。如果又发现了新的问题，那么还需要再次修改。这个 review - revise 的过程可能会反复几次，很正常。
当然，在请他人 review 之前，Technical Writer 也可以先自己 review 一遍，尽量避免低级错误，不浪费他人的时间。
哈哈，问题又来了~通常，刚写完一篇文章的人是很不情愿再去看自己写的东西的，此时就可以使用一些语法拼写检查的小工具来协助你了。
我在之前的一篇文章 Technical Writer 日常工作中好用的小工具 中有推荐，有需要的小伙伴可以戳链接去瞅瞅~
如果你觉得自己足够细心，根本不需要小工具来协助你，我佩服你的能力，但还是建议用一下小工具。因为，你可能也会有状态不好的时候，有疲劳打盹的时候，有不知道自己写了一堆什么鬼东西的时候……不要跟自己和小工具过不去。
等文档定稿之后，就可以在平台上发布了，一般很容易操作。不同的公司的文档发布平台也会不一样，Technical Writer 使用的写作工具也不一样。
文档发布之后，并不代表着结束。根据我的工作经历，即便是已经发布的文档，也依然有可能存在问题，无论是大公司还是小公司的文档。例如：未发现的文字错误、失效的链接、与最新的产品已不匹配的描述和步骤等。Technical Writer 需要及时跟进产品动态，以便及时更新文档。
写技术文档不是一劳永逸的，只要产品在更新，就需要 Technical Writer 一直维护下去。
以上分享的是一个完整的技术文档从零到有的过程。日常工作中，有时不需要从头开始，而只是对原有文档的增删修改，那就可以省去一些相应的环节。
如果你也是一枚 Technical Writer，也期待听到你对技术写作流程的见解，欢迎留言交流哦~
Reference:
你可能想读 ：
Technical Writer 日常工作中好用的小工具
技术翻译需要有 Technical Writer 的 sense
深度解析关于技术翻译的六个认知误区
如何让你的内容输出更加专业更有设计感？
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？（一）
有哪些适合技术传播从业者关注的优质博客？（二）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（上篇）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（下篇）
英语技术文档的标题到底该大写还是小写？
如何使用正则表达式批量添加和删除字符？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
如何为 Markdown 文件自动生成目录？
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
优质译文不应止于正确，还要 Well-Organized
写在入职技术型创业公司 PingCAP 一个月之后
揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记
-END-