对文档的一些思考

在平时写代码时总会阅读许多文档，也因此对如何编写文档有了一些自己的看法。

起因

最近正好在试着写一个 VS Code 的主题，因此需要对照官方文档里给出的 api 来编写大量 内容。想起自己以前阅读过的各种各样的文档，也想总结一下我心目中文档的最佳形态。

此处所指的文档仅包括应用程序或库的使用文档。由于目前正在阅读 VS Code 的文档，因此 接下来的许多部分将提供 VS Code 的例子。

应该有什么

简单上手

一份文档首先需要一个最简单的案例，让用户能够快速上手，体验到应用或库的重要内容，能够 让用户迅速明白是否这是其正在寻找的解决方案。

这样的一个案例不需要非常复杂。相反，应该简单易懂，给出一个简易的最佳实践。最好在完全 不需要用户学习的情况下就能够体验到尽可能多的内容，防止因需要过久学习且缺少反馈而失去 用户。

在提供了最简案例后，需要给出几个详细案例。这些案例最好是开发者实际正在使用的简化版， 用于解决该应用或库开发时希望能够解决的问题。这些案例通常是使用者找到这一应用或库后 最希望解决的问题，因此需要提供这些案例来帮助使用者快速解决。

最后，还可以提供一些链接来提供一条学习路线，方便开发者根据需求跳转学习。

许多文档都会通过 get started 的部分来提供这一内容。

详细 api

最后，如果是库且没有自动生成文档的能力，或是应用且具有扩展功能的，可以提供完整的 api 给开发者以便使用。对每个 api 最好都有简单的注解，方便理解用途。如果是 ui 相关 的 api，最好还能包括对应的截图。

另外，许多 api 可能是相互关联的，因此最好能够加上跳转链接，方便查询使用。

良好的排版

文档应该有一个良好的排版来方便阅读。

如果文档非常短，那么也许将所有内容写在一起是一个不错的选择，便于阅读的同时，页面 显示的内容不会太少，让人觉得文档不用心。

但如果内容较多，就应该做好分页工作，例如一个主题一页，帮助读者迅速找到需要的内容。 如果一页里的内容依然非常多，就应该添加完善的目录。目录不应出现在文档的最上方，而应 在不遮挡内容的前提下浮动在页面左右，便于随时跳转，以及明确阅读的进度。

这里以 VS Code 的文档举例，内容相当丰富，虽然有些页面内容很多，但也有浮动的目录栏 便于跳转。

但像这里，就会出现内容 过多，目录也无法显示完全的情况，对开发者不够友好。

一些总结

以上这些内容是我读了许多文档之后，感触最深的一些内容。也许有时候自己也会因为懒而不 好好写文档，无法满足上述这些要求，但是对于应用或库来说，文档的确是非常关键的一环。

一份好的文档读起来应当是非常舒心的。应当帮助开发者迅速了解适用范围，并给出一些最佳 实践，帮助开发者节省 debug 的时间。也能够在需要的时候提供足够的细节内容，如 api 等， 使得开发者能快速找到问题的解决方案。