由于会经常查阅yui文档，yui文档分为代码级别的APIDoc和向导级别的guideline。 APIDoc适合做开发过程中的工具书，guideline适合初学和二次深入。如此富有层次感的文档让人使用起来非常顺手也很易找到自己想要的东西。都说yui team多少有一些学院派的影子，不错，学术上的纯粹性除了给具体前端实践提供清晰的方向之外，在技术上的沉淀也让人觉得很有味道，yui文档是这种沉淀的最好体现。这种“由浅入深”的文档学术味道浓厚，带给人的思考源于技术而高于技术，是值得崇尚的。
我们在做项目的时候，也会写文档，但文档写的如此之草率以至于没什么人来读，或者读了也读不能立即读明白，最主要的原因是文档的易读性很差。那么，我们应当如何来写一个易读的文档，最大体现文档的价值呢？
一个易读的文档并不意味着其内容的浅薄，相反，它一定包含内容的渐进性和结构性。想想我们是怎么浏览网页的，门户网站总会首先展现导航，新闻的分类也一定是按照政治相关性的强弱划分，不论是新浪还是网易，总是首先看到政治新闻最后看到娱乐八卦。因此，我们浏览这些新闻标题的时候脑海中也有一种思维定势，最重要的一定是最前面，最不重要的一定是在最后面。这是我们通常的网页阅读习惯。因此，我们在写文档的时候或多或少受这个习惯的影响，总是习下意识的将一些重要关键内容放在醒目位置，期望读者一眼就能够看到。
实际上，文档和门户网站有本质区别，简单讲，文档就是一个指导性的工具，往低了讲，它和使用手册类似，往高了讲，它和教科书很像。所以文档的索引一定是有序的，如果是操作手册，索引顺序则需要从易操作渐进到难操作，如果是教科书，索引顺序则需按照绪论、原理、关键的创新点、实践这个顺序来走。yui文档的每个条目也基本上都是按照这个顺序来写：介绍、原理、使用，这是符合我们读书习惯的。因为我们读书通常都是由前言读到绪论，再渐进渐深。所以文档的渐进性是文档可读性的一个重要标准。
另外一个重要的方面是分类，我们在写文档的时候总是会将内容分类展现，比如这个分类：“工作相关”、“规范指南”、“辅助信息”、“学习交流”、“人在江湖”、“工作文档”，我们应当如可评价这种分类呢？其实这种分类的初衷盖源自工具书，比如百科全书、新华字典，这些书的信息量极大，因此他们将信息的分类也很极端，所有类目必然相互正交，这样才会形成一个精确的树状索引，不能说快速，至少说能让读者很精确的找到他想找的信息。而我们在写技术文档的时候，常常被并不太大的信息量把自己搞的晕头转向，看刚才的分类，比如我想找一个填写周报的模板，我应当在“工作入口”中找呢还是在“工作文档”中找呢？“工作入口”貌似是给新员工看的，文案的东西大概会在这个分类中，但看分类名称又好像在“工作文档”中，再比如我想看一个编辑器的组件实例代码，我是在“规范指南”中找呢还是在“辅助信息”中找呢？ “规范指南”貌似是一个说明手册放一些条款条文的东东，“辅助信息”是不是就像书中的放代码实例的附录呢？OMG，还没开始下一级的查找我就已经晕菜了。原因在于这些分类太过随意、各自交集太大、不够正交。这对文档可读性提高是没有任何帮助的。
现在回想起来，当初写毕业论文的确有很多难得的收获，如何从浅入深的写一篇论文，怎样把大量信息进行正交分类，这些点滴的积累在任何细节都有可能用的上的。因此：
- 索引不是谁都能写的，一定需要掌握最大信息量的人来写，以便做到分类正交
- 索引顺序应当由浅入深，原理性的指导性文档在前，实例文档在后
- 向导性文档和代码级的API分开，以便针对不同层次的读者
- 每个类目的内容多到一定级别要有子向导
- 每个类目内容安排顺序应当为介绍、原理、使用