`

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

阅读更多
很多人说,不知道怎么写文档,都是凭着感觉写。

网上也很少有资料,教你写文档。这已经影响了中文软件的发展。



英语世界里,文档非常受重视,许多公司和组织都有自己的文档规范,清楚地规定写作要求,比如微软、MailChimp、Apple、Yahoo、docker、Struts 等等(维基百科有一份完整的清单)。中文的也有不少,但都不令人满意,要么太简单,要么不太适用。

我就动手,参考上面的规范,也结合自己的实践,总结了一份简单的《中文技术文档的写作规范》。

标题
文本
段落
数值
标点符号
章节结构
我希望,这样可以抛砖引玉,让更多人重视文档,进而真正出现大家普遍接受的文档规范。

下面是关于写作风格的一个片段。欢迎提交 Issue 和 PR 补充。

=================================

写作风格
(摘自《中文技术文档的写作规范》)



如果使用了被动语态,应考虑更改为主动语态。

不使用非正式的语言风格。

用对"的"、"地"、"得"。

使用代词时(比如"其"、"该"、"此"、"这"等词),必须明确指代的内容,保证只有一个含义。
阅读全文直接点击:http://click.aliyun.com/m/9973/
分享到:
评论

相关推荐

    python阮一峰-阮一峰:Fishshell入门教程.pdf

    《Python阮一峰:Fishshell入门教程》 Python开发者在日常工作中经常需要与命令行交互,而Shell作为命令行的接口,其重要性不言而喻。常见的Shell有Bash和zsh,但本文作者阮一峰推崇的是Fish Shell,认为它在易用性...

    阮一峰:回顾网站-无密码登录-的常见做法.docx

    尽管Persona试图简化OpenID的复杂性,但其技术要求较高,且需要邮件服务器支持,使其推广面临挑战。 【OAuth】协议虽与第三方账户相关,但更侧重于授权服务,允许外部应用访问第三方网站的用户数据,而非仅进行身份...

    阮一峰es6教程文档源码

    这份源码正是他的教程文档的原始代码,可以帮助读者深入理解ES6的实现原理和应用技巧。** 1. **箭头函数**:箭头函数是ES6中的一种新语法,它使得函数的定义更加简洁。例如,`const add = (x, y) => x + y;`。箭头...

    es6 阮一峰

    《ES6 阮一峰》是一本详细解读ECMAScript 6(也称为ES2015)标准的中文指南,由知名前端开发者阮一峰编写。这本书以PDF格式提供,适合读者在线阅读或下载后离线学习,并且允许在文档上做笔记,为学习过程提供了便利...

    阮一峰 JavaScript 教程.pdf

    以上内容详细介绍了阮一峰所编写的 JavaScript 教程中涵盖的知识点,从基础语法到高级特性,覆盖了编程、开发中需要掌握的大部分概念和用法。这本教程特别适合初学者作为入门书籍,内容详尽,理论与实践相结合,配合...

    VitePress构建阮一峰的技术周刊.zip

    VitePress是由知名前端开发者阮一峰创建的一个快速、简洁且高效的静态站点生成器,尤其适合用来构建技术文档和博客。它基于Vue.js生态,利用了Vite的强大特性,为开发者提供了一种现代化的构建流程。这个压缩包...

    阮一峰_理解OAuth 2.01

    在本文中,作者阮一峰详细解释了OAuth 2.0 的设计思路和工作流程,以便读者能够更好地理解和应用这一授权框架。 首先,OAuth 2.0 应用于第三方应用程序(客户端)需要访问用户在服务提供商(如Google)上的数据但又...

    阮一峰JavaScript教程.pdf

    阮一峰JavaScript教程.pdf 阮一峰JavaScript教程是一本系统的JavaScript教程,涵盖了JavaScript语言的核心语法、数据类型、函数、数组、对象、异步操作、DOM操作等方面的知识点。下面是该教程的详细知识点总结: ...

    阮一峰读过的一些书籍集合.zip

    这个文件很可能是阮一峰,一位知名的IT博主和技术专家,分享的他的阅读清单。通过这个压缩包,我们可以了解到阮一峰在IT领域所关注的知识点和推荐的书籍,这些书籍可能涵盖编程、计算机科学、软件工程、互联网技术等...

    ES6入门基础-阮一峰

    阮一峰先生编写的《ECMAScript 6 入门》是一本深入浅出的教程,帮助开发者全面了解和掌握这些新特性。** 1. **let 和 const 声明** 在ES6之前,JavaScript只有`var`关键字用于声明变量,但`let`和`const`的引入...

    如何变得有思想mobi 高清带书签 阮一峰博客选集

    如何变得有思想mobi是 阮一峰博客选集,囊括了作者对各种问题的思考,以及如何变得有思想mobi围绕的主题是试图理解这个世界。如何变得有思想mobi的内容非常广泛,涉及观点、文学、历史、科技、影视等方面。阮一峰在...

    《ECMAScript 6 入门-阮一峰》PDF完整版

    阮一峰先生的《ECMAScript 6 入门》是一本深入浅出介绍这一版本的权威指南。** 在ES6中,最重要的特性之一是类(Class)和模块(Module)。类的引入使得面向对象编程更加直观,它通过`class`关键字定义,提供了构造...

    阮一峰《ECMA6入门》PDF版本

    **阮一峰《ECMAScript6入门》PDF版本** ECMAScript6,通常简称为ES6,是JavaScript语言的一个重要版本更新,它在2015年被正式发布,为这个世界上最广泛使用的脚本语言带来了许多新特性。阮一峰老师的《ECMAScript6...

    es6标准入门_阮一峰最新版_第三版pdf

    阮一峰的《ES6标准入门》是学习这一语言版本的经典教程,特别是其第三版,不仅涵盖了ES6的核心内容,还对后续的ES7等语法做了详细介绍。 1. **箭头函数**:箭头函数是ES6引入的一种新的函数定义方式,它具有简洁的...

    《ECMAScript 6 入门》 Javascript nodejs 教程 阮一峰 带书签

    《ECMAScript 6 入门》是阮一峰编写的JavaScript编程教程,专注于介绍ECMAScript 6(也称为ES6或ES2015)的新特性和语法改进。这本书是JavaScript开发者深入理解现代JavaScript编程的基础读物,特别适合已经掌握基本...

    ECMAScript 6入门 第二版 阮一峰 pdf完整版

    ECMAScript 6入门书籍的作者阮一峰,是一名知名的前端技术专家,他的书籍详细介绍了ES6的各个新特性,并且在讲解的过程中辅以大量的示例代码,使得读者能够更加容易地理解和掌握这些新特性。本书适合已经了解ES5的...

    阮一峰《C 语言教程》从入门到精通

    《阮一峰的C语言教程》是一本全面深入学习C语言的教程,涵盖了从入门到精通的各个层次的知识。教程内容丰富,旨在帮助初学者掌握C语言的基本概念和高级特性,同时也适合有一定基础的开发者用来巩固和提升技能。 ...

Global site tag (gtag.js) - Google Analytics