很多人说,不知道怎么写文档,都是凭着感觉写。
网上也很少有资料,教你写文档。这已经影响了中文软件的发展。
英语世界里,文档非常受重视,许多公司和组织都有自己的文档规范,清楚地规定写作要求,比如微软、MailChimp、Apple、Yahoo、docker、Struts 等等(维基百科有一份完整的清单)。中文的也有不少,但都不令人满意,要么太简单,要么不太适用。
我就动手,参考上面的规范,也结合自己的实践,总结了一份简单的《中文技术文档的写作规范》。
标题
文本
段落
数值
标点符号
章节结构
我希望,这样可以抛砖引玉,让更多人重视文档,进而真正出现大家普遍接受的文档规范。
下面是关于写作风格的一个片段。欢迎提交 Issue 和 PR 补充。
=================================
写作风格
(摘自《中文技术文档的写作规范》)
如果使用了被动语态,应考虑更改为主动语态。
不使用非正式的语言风格。
用对"的"、"地"、"得"。
使用代词时(比如"其"、"该"、"此"、"这"等词),必须明确指代的内容,保证只有一个含义。
阅读全文直接点击:
http://click.aliyun.com/m/9973/
分享到:
相关推荐
《Python阮一峰:Fishshell入门教程》 Python开发者在日常工作中经常需要与命令行交互,而Shell作为命令行的接口,其重要性不言而喻。常见的Shell有Bash和zsh,但本文作者阮一峰推崇的是Fish Shell,认为它在易用性...
尽管Persona试图简化OpenID的复杂性,但其技术要求较高,且需要邮件服务器支持,使其推广面临挑战。 【OAuth】协议虽与第三方账户相关,但更侧重于授权服务,允许外部应用访问第三方网站的用户数据,而非仅进行身份...
这份源码正是他的教程文档的原始代码,可以帮助读者深入理解ES6的实现原理和应用技巧。** 1. **箭头函数**:箭头函数是ES6中的一种新语法,它使得函数的定义更加简洁。例如,`const add = (x, y) => x + y;`。箭头...
《ES6 阮一峰》是一本详细解读ECMAScript 6(也称为ES2015)标准的中文指南,由知名前端开发者阮一峰编写。这本书以PDF格式提供,适合读者在线阅读或下载后离线学习,并且允许在文档上做笔记,为学习过程提供了便利...
以上内容详细介绍了阮一峰所编写的 JavaScript 教程中涵盖的知识点,从基础语法到高级特性,覆盖了编程、开发中需要掌握的大部分概念和用法。这本教程特别适合初学者作为入门书籍,内容详尽,理论与实践相结合,配合...
VitePress是由知名前端开发者阮一峰创建的一个快速、简洁且高效的静态站点生成器,尤其适合用来构建技术文档和博客。它基于Vue.js生态,利用了Vite的强大特性,为开发者提供了一种现代化的构建流程。这个压缩包...
在本文中,作者阮一峰详细解释了OAuth 2.0 的设计思路和工作流程,以便读者能够更好地理解和应用这一授权框架。 首先,OAuth 2.0 应用于第三方应用程序(客户端)需要访问用户在服务提供商(如Google)上的数据但又...
阮一峰JavaScript教程.pdf 阮一峰JavaScript教程是一本系统的JavaScript教程,涵盖了JavaScript语言的核心语法、数据类型、函数、数组、对象、异步操作、DOM操作等方面的知识点。下面是该教程的详细知识点总结: ...
这个文件很可能是阮一峰,一位知名的IT博主和技术专家,分享的他的阅读清单。通过这个压缩包,我们可以了解到阮一峰在IT领域所关注的知识点和推荐的书籍,这些书籍可能涵盖编程、计算机科学、软件工程、互联网技术等...
阮一峰先生编写的《ECMAScript 6 入门》是一本深入浅出的教程,帮助开发者全面了解和掌握这些新特性。** 1. **let 和 const 声明** 在ES6之前,JavaScript只有`var`关键字用于声明变量,但`let`和`const`的引入...
如何变得有思想mobi是 阮一峰博客选集,囊括了作者对各种问题的思考,以及如何变得有思想mobi围绕的主题是试图理解这个世界。如何变得有思想mobi的内容非常广泛,涉及观点、文学、历史、科技、影视等方面。阮一峰在...
阮一峰先生的《ECMAScript 6 入门》是一本深入浅出介绍这一版本的权威指南。** 在ES6中,最重要的特性之一是类(Class)和模块(Module)。类的引入使得面向对象编程更加直观,它通过`class`关键字定义,提供了构造...
**阮一峰《ECMAScript6入门》PDF版本** ECMAScript6,通常简称为ES6,是JavaScript语言的一个重要版本更新,它在2015年被正式发布,为这个世界上最广泛使用的脚本语言带来了许多新特性。阮一峰老师的《ECMAScript6...
阮一峰的《ES6标准入门》是学习这一语言版本的经典教程,特别是其第三版,不仅涵盖了ES6的核心内容,还对后续的ES7等语法做了详细介绍。 1. **箭头函数**:箭头函数是ES6引入的一种新的函数定义方式,它具有简洁的...
《ECMAScript 6 入门》是阮一峰编写的JavaScript编程教程,专注于介绍ECMAScript 6(也称为ES6或ES2015)的新特性和语法改进。这本书是JavaScript开发者深入理解现代JavaScript编程的基础读物,特别适合已经掌握基本...
ECMAScript 6入门书籍的作者阮一峰,是一名知名的前端技术专家,他的书籍详细介绍了ES6的各个新特性,并且在讲解的过程中辅以大量的示例代码,使得读者能够更加容易地理解和掌握这些新特性。本书适合已经了解ES5的...
《阮一峰的C语言教程》是一本全面深入学习C语言的教程,涵盖了从入门到精通的各个层次的知识。教程内容丰富,旨在帮助初学者掌握C语言的基本概念和高级特性,同时也适合有一定基础的开发者用来巩固和提升技能。 ...