都夸Vue官方文档写得好，是有原因的

1039次阅读  |  发布于3年以前

文档，可以说是一件最容易做的事情，但是同时又是一件最难做好的一件事情。我们也总是在看各种文档，也在吐槽这个文档写的不好，那个写的不好，亦或者回过头来，吐槽我们自己的文档写的也不好。

Vue 能够这么火爆，其文档的贡献也是不可磨灭的。在开源领域，也有一个核心精神就是文档先行。那 Vue 就是这里的佼佼者，也是大家喜欢 Vue，Vue 受到这么多开发者喜欢的其中一个核心原因。

那 Vue 的文档是怎么设计的呢？包含哪些部分？对于我们自身的项目而言，如果也要写文档，我们可以从中借鉴些什么呢？

这里也抛出一个问题：Vue 的文档有这么多的部分，如果你是一个重度的 Vue 用户，是否你已经通读过 Vue 的文档，了解了 Vue 的方方面面？

正文分析

What

Vue 的文档放在 https://cn.vuejs.org/index.html 上的，当然如果英语好，可以访问英文版本 https://vuejs.org/index.html。

这里所列的就是首页，我们可以看到整个文档所包含的内容：

基本上包含了 Vue 相关的方方面面了。

How

那有了这些导航和概览的东西是不能说文档写的好的，只能说写的比较全，我们可以进一步挑一些部分进行分析：

首页

首页的重要性不言而喻，是属于第一印象，而且需要抓住用户，Vue 的首页的样子：

最核心的：

整体来看，核心就是做好第一印象，吸引用户，这里的重点也就是面向新用户，抓住他们。

教程

教程对于一个项目的重要性不言而喻，最重要的就是教会开发者入门且能够做复杂应用，以及帮助用户理解设计和一些细节，理论上学会了教程相关的内容，你应该是一名合格的 Vue 开发者了。

我们可以从 Vue 的教程来看：

从基础到更多的一些生态方面的涉及都包含在内了，很全面同时又比较容易认知，这是教程的核心。

接下来我们就以：基础、深入了解组件、过渡 & 动画 来详细分析分析他们。

基础部分

对于新手入门而言，基础部分则是十分重要的，这里最核心的就是把用户当成纯新用户，甚至是对前端都不怎么了解的用户，去一步步教会他们怎么实现功能，并且这些经验是在以后深入使用 Vue 也是一样有用的。

可以大概理解为：照葫芦画瓢，完成之后，惊呼：Amazing！而且，除此之外，Vue 教程每部分都有相关的视频搭配，更生动形象了！

现在看下教程中的核心中的核心，基础部分。

Vue 中将基础的部分划分为了以下几个部分：

可以看出，这里的基础部分的内容的最核心的东西：带你认识各个不同的概念和用法，不去深究（会有专门的篇幅去讲，以链接链过去），聚焦最核心的这个功能可能出现的情况以及相关的注意事项。

整个的模式大概为：

基本上，即使你是一个前端小白，照着给你的展示的东西，也是可以大概理解基本的概念以及特性的。此时的你也不需要深入了解他们，只需要知道有这些东西，他们的用法大概是怎么样的，或者是解决什么场景的问题，将来的遇到的时候可以找到这部分教程。

而且还有一点细节的：

深入了解组件

这里基本上是上一节【基础/组件基础】的延伸。组件是 Vue 中的核心设计之一，所以单独拿出来一个大大的篇幅来详细的介绍组件是十分有必要的。

一起来看下，Vue 关于这块是如何“深入浅出”的：

虽然是深入的部分，但是在讲述的时候也基本上遵从了前边在基础中所涉及的：示例啊、聚焦相关的模式。额外的点，所有的这些部分都顶部加了友情提示，你需要了解组件基础，防止因为对组件不了解所导致的问题（从标题上也可以看出，是属于深入的部分，有一定的成本在的）。

同时，你也注意到了，在 Vue 的很多地方都涉及到大小写、驼峰等相关的解释和规则，基本上所有的都源自于 DOM 模板解析所带来的。

过渡 & 动画

过渡 & 动画这块也是 Vue 的特性之一，功能还是非常强大的。

在过渡和动画这里，详细展示了 Vue 中提供的很好用的特性，做过渡和动画的各种示例和演示，满足你的各个场景的需求。

到这里一些教程相关的我们挑选了部分做了一些大概的分析，你会发现他们的模式或者原则基本是一致的：

额外的，在其他模块里，同样在教程的范围之内，也包含了一些比较深入的内容，但是是为了帮助你更好的理解 Vue，更好的使用 Vue 的，例如内在模块所讲的【深入响应式原理】相关的内容，就是可以帮助你深入理解 Vue 的响应式相关原理，遇到问题的时候可以快速定位问题。也包含了在更多中会涉及【对比其他框架】，可以看到官方对于相关的一些框架是怎么对比的，有哪些思路去分析的。

API

API 是一个框架对外暴露的所有交互接口的集合，对于这部分而言，我们要做的不是简单的罗列，而是需要有一些规则的，我们就来看看 Vue 是怎么做的。

一些我们可以分析出来的规则：

这样下来，你既可以了解整体 API 的全貌和分类，相对应的他们大概可以完成什么功能你也是了解的，方便你后续在实际使用中有记不起来的或者需要确认的可以很方便很快速的来到 API 这里进行定位。

风格指南

这个基本上是 Vue 最特有的一个部分，官方明确给出了作为 Vue 开发者应该遵从的一些风格指南。这是帮助开发者回避错误、小纠结和反模式的最好参考。这个也约等于是一份 Vue 的最佳实践，你也会发现，你在开发过程中如果遵从了这份风格指南的话，基本上不会出现啥问题。

这份风格指南对规则进行了四大类的划分：

并且给你了详细的解释，给到你建议和参考。

接下来就是每一部分详细的规则介绍，这里大概看下：

这个相当于是一个规范，一个最佳实践，如果大家都能遵守上述的约定，那么大家阅读代码或者CR的时候的成本就会降低很多。并且，还可以降低很多错误或者警告的发生。

示例

示例 example 是一个完整的展示，而不是像之前在教程中的一个个的小示例 demo 展示，本质上这里的示例，是一个mini的应用。

Vue 中大概包含了：Markdown 编辑器、GitHub提交、网格组件、树形视图、SVG图标、模式组件、具有伸缩性的 Header、内嵌组件、实时deepstreamHub、Firebase + 验证、ToDoMVC、HackerNews 克隆。

这里的每一个示例都基本上用到了 Vue 中不同功能，或者是不同的写法和组织方式，大部分大家都可以直接在官网上直接看到效果以及代码实现。十分的直观，而且你也可以按照自己的思路进一步修改，做属于你自己的示例。

Cookbook

首先意识到 Cookbook 和教程的区别，这个在文档中也有详细的描述：

那么 Cookbook 的目标是什么呢？

Vue 目前提供的这部分的内容是按照如下规则的：

这些在 Vue 中已经有了详尽的解释了，包含了动机、目标、规范。

Why

个人认为，最核心的一个点，作为一个开源项目，甚至是作为一个项目，如果你有用户，那么用户怎么样可以使用你的这个项目就十分重要了。口口相传肯定是不可以的，那就只能靠文档。而且文档还有一个好处，利于 SEO，进一步增强了生态。

文档先行或者要把文档写好，在开源领域中这是一个至关重要的点，夸张一点，有些情况下可能是决定了一个项目生死或者生命周期的重要指标之一。

公认的，大家都认为 Vue 的文档写得好，那么从原因视角来看，这个是 Vue 开源项目的核心，不可或缺的一部分。不仅仅要把代码写的好，文档要写的好，测试也要做好，开源协作要做好，等等。这是一个对项目负责、对开发者负责的核心态度，当然，付出就会有回报，相信也正是因为 Vue 文档的全面、简单易用，Vue 生态才变得更加繁荣了，两者也是密不可分的。

总结

我们基本上分析了 Vue 文档的部分核心模块的内容，包含了：

通过对他们的详细的一个分析，我们可以发现，Vue在整个的文档设计上，还是做了很好的抽象和分类的。既不会让开发者觉得文档很多，同时又感觉很有层次，各个模块部分负责的事情很清晰。

这里我们可以做一个大概的总结和思考，以便于后续我们在写文档的时候有所借鉴和学习：

整体大纲

这里核心中的核心就是首页、学习和生态了。而对于学习的部分，又进行了一个层次的拆解：

对于我们而言，也是可以参考学习这种文档的大纲形式，根据我们的情况按需的去增删。

内容拆解

这部分，主要核心就是文档中五个部分的拆解：

可以看出，针对于不同的模块，我们拆解的核心要关注的还是不一样的，但是也不能形成散乱，他们之间是相互关联的关系，当有相关的关联的时候，是给到链接彼此跳转的。最终形成的是一个具有整体划分，各个模块之间彼此结合，有一定层级关系的这样的一种拆解方式来阐述，供开发者学习、查阅。

其他

当然，这里并不是说其他的部分不重要，这个是根据项目情况去选择的，我们这里更多的是举例，通过这些大纲和拆解，可以帮助我们写一个更好的文档：

  1. 意识：文档的重要性，不可或缺的价值，甚至比项目本身更为重要
  2. 前提：开发者都是新手，相关依赖要描述清楚
  3. 内容：整体性、有层次、模块划分清晰，模块内容本身聚焦、不发散
  4. 语言：简单、准确、易于理解
  5. 生态：给到描述和入口，解决你更多的问题
  6. 团队：成员荣誉，也是影响力的体现

Copyright© 2013-2020

All Rights Reserved 京ICP备2023019179号-8