--- group: Engineering order: 1.1 --- # Writing Specification ## 前言 在这个信息爆炸的时代，我们无时无刻不和文档打交道。我们每天都在阅读文档，有时我们自己也需要撰写文档。 因此，我们在撰写文档的时候如果能遵循一点良好的规约，将能**提升所有人的阅读体验**。 在此，文档的含义非常广泛，可以指代任何供人类阅读的文本材料。包括但不限于：Readme、Changelog、代码注释、上手指南、Issue 说明和PPT 分享等。 ## 1 空格 - 1.1 `mandatory` 中英文之间需要增加空格 ```markdown HTML定义网页的结构与内容，CSS定义其格式与样式，而JavaScript则为网页增加可交互性，创作功能丰富的Web应用。 HTML 定义网页的结构与内容，CSS 定义其格式与样式，而 JavaScript 则为网页增加可交互性，创作功能丰富的 Web 应用。 ``` - 1.2 `mandatory` 中英文与数字之间需要增加空格 ```markdown 截至2012年，所有的现代浏览器都完整的支持 ECMAScript5.1，旧版本的浏览器至少支持 ECMAScript3 标准。 截至 2012 年，所有的现代浏览器都完整的支持 ECMAScript 5.1，旧版本的浏览器至少支持 ECMAScript 3 标准。 ``` - 1.3 `mandatory` 全角标点与其他字符之间不加空格 ```markdown 不像 UDP， HTTP 是一个不会静默丢失消息的协议。 不像 UDP，HTTP 是一个不会静默丢失消息的协议。 ``` - 1.4 `mandatory` 半角标点与其他字符之间需要增加空格 ```markdown Cookie 主要用于以下三个方面： 1.会话状态管理（如用户登录状态、购物车、游戏分数或其它需要记录的信息）2.个性化设置（如用户自定义设置、主题等）3.浏览器行为跟踪（如跟踪分析用户行为等） Cookie 主要用于以下三个方面： 1. 会话状态管理（如用户登录状态、购物车、游戏分数或其它需要记录的信息） 2. 个性化设置（如用户自定义设置、主题等） 3. 浏览器行为跟踪（如跟踪分析用户行为等） 我+你=世界。 我 + 你 = 世界。 ``` - 1.5 `recommended` 链接文字前后不需要增加空格 ```markdown [了解更多](https://developer.mozilla.org/zh-CN/docs/Web) 开发技术相关知识。 [了解更多](https://developer.mozilla.org/zh-CN/docs/Web)开发技术相关知识。 ``` ## 2 标点符号 - 2.1 `recommended` 正确使用引号 中文句子内夹用英文句子时，该英文句子用中文双引号标示，保留英文句子内部的英文标点符号，句末使用中文标点。 ```markdown 他写的是 "Hello, world!"。 他写的是‘Hello, world!’。 他写的是“Hello，world！”。 他写的是“Hello, world!”。 ``` - 2.2 `recommended` 正确使用省略号 中文省略号的形式为“……”（中文输入法下 SHIFT + 6），6 个居中小圆点；英文省略号的形式为“...”，3 个齐线小圆点。 夹用英文的中文句子里，英文内部的省略使用英文省略号；中文内部的省略使用中文省略号。 ```markdown 省略号是 3 个小圆点... 省略号是 6 个齐线小圆点...... 省略号是 6 个句号。。。。。。 省略号是 6 个居中小圆点，占两个全角空格…… ``` - 2.3 `recommended` 正确使用破折号 中文破折号的形式为“——”，长度相当于两个汉字的长度。 ```markdown 第三方框架和库--用来快速构建网站和应用。 第三方框架和库——用来快速构建网站和应用。 ``` ## 3 全角和半角 - 3.1 `mandatory` 中文标点符号使用全角 ```markdown 前端框架: React、Vue、Angular。 前端框架：React, Vue, Angular。 前端框架：React、Vue、Angular。 至少熟悉一门非前端的语言(如 Java、PHP、C、C++、Python、Ruby)，并有实践经验！ 至少熟悉一门非前端的语言（如 Java、PHP、C、C++、Python、Ruby），并有实践经验！ ``` - 3.2 `mandatory` 英文和数字使用半角 ```markdown 该版本正式名称为 ＥＣＭＡＳｃｒｉｐｔ ２０１５，但通常被称为 ＥＣＭＡＳｃｒｉｐｔ ６ 或者 ＥＳ６。 该版本正式名称为 ECMAScript 2015，但通常被称为 ECMAScript 6 或者 ES6。 ``` - 3.3 `mandatory` 完整的英文整句和特殊名词使用半角标点 ```markdown 乔布斯那句话是怎么说的？「Stay hungry，stay foolish。」 推荐你阅读《Hackers＆Painters：Big Ideas from the Computer Age》，非常的有趣。 乔布斯那句话是怎么说的？「Stay hungry, stay foolish.」 推荐你阅读《Hackers & Painters: Big Ideas from the Computer Age》，非常的有趣。 ``` ## 4 名词 - 4.1 `mandatory` 正确地拼写英文专有词汇 ```markdown 我们需要一位熟悉 Js、h5，至少理解一种框架（如 backbone、angular、RJS 等）的 FED。 我们需要一位熟悉 JavaScript、HTML5，至少理解一种框架（如 Backbone.js、AngularJS、React 等）的前端开发者。 ``` ## 附录 前端常用专有名词： ```markdown HTML, CSS, JavaScript/JS, AJAX, JSON, DOM, BOM, Less, HTTP, HTTPS, WebSocket, ECMAScript, ECMAScript 2015, ECMAScript 6, ES6, ES2015 jQuery, jQuery UI, jQuery Mobile, YUI, Zepto, Dojo React, React Native, Bootstrap, RequireJS, Sea.js, AngularJS, Backbone.js Gulp, Grunt, webpack, Yeoman, npm, spm, Babel Mocha, Jasmine, Should.js PHP, Java, Node.js MySQL, MongoDB, Redis Apache, Nginx GitHub, GitLab, GitCafe Chrome, Firefox, Safari, Internet Explore/IE, IE 7, Opera, UC Android, iOS, Windows, OS X, Ubuntu, Linux, Debian PC, Mobile, H5 MacBook, MacBook Pro, MacBook Air, iMac, Mac Pro, Mac mini iPad Air, iPad Air 2, iPad mini, iPhone, iPhone 6s, iPhone 6s Plus, Apple Watch Alibaba, Taobao, Google, Alphabet, Apple, Microsoft, Yahoo FPS, UI, URL, URI, URLs, URIs ``` ## 参考资料 - [《中文文案排版指北》](https://github.com/sparanoid/chinese-copywriting-guidelines) - [《标点符号用法》](http://www.moe.gov.cn/ewebeditor/uploadfile/2015/01/13/20150113091548267.pdf) - [夹用英文的中文文本的标点符号用法（草案）](http://www.moe.gov.cn/ewebeditor/uploadfile/2015/01/13/20150113092346124.pdf) - [《中文排版需求》](https://www.w3.org/TR/clreq/)