我们的的Potion插件有一些很有用的功能，但是如果我们不提供文档的话告诉他们这个插件能干什么的话，那么它对于任务人都是没有用的。
Vim自身的文档非常完美。它不啰嗦，但是覆盖了全部的功能。它的文档也知道了很多插件的作者来完善它们自己的文档，从而也就在Vimscript社区里形成了良好的文档文化。
当你在Vim里阅读一个:help的话题时，你会发现相比较其他内容而言，有些内容是高亮的。我们来看看这个是如何做到的。
打开任何一个帮助文档（例如:help help），然后运行:set filetype?。Vim会显示filetype=hep。现在运行:set filetype=text，你会发现高亮的地方都消失了。再次运行:set filetype=help这些高亮又出现了。
事实上，Vim帮助文件和其他文件一样，都是语法高亮后的文本！这也就意味着你可以编写你自己的文档，然后也能够进行高亮。
在你的创建库里创建一个doc/potion.txt文件。当索引帮助文档的时候，Vim/Pathogen会查找doc文件夹下地内容，所以我们只需要在这里编写我们的帮助文档即可。
在Vim里打开这个文件，并且运行:set filetype=help，当你输入内容的时候，你会发现有语法高亮的功能。
帮助文件的格式取决于个人的喜好。这样说了，那我就采取一种普遍被现代Vimscript社区所采用的一种比较流行的方式来组织它们。
帮助文件的第一行应该包含帮助文件的名称，接着是一行描述这个插件的文本。接下来就是你的potion.txt的第一行。
*potion.txt* functionality for the potion programming language
通过星号围起来的文本创建了一个可以被跳转的“标记”。运行:HelpTags命令来告诉Pathogen来重新构建帮助标签的索取，然后打开一个新的Vim窗口，运行:help potion.txt。Vim会像打开其他帮助文档一样打开你的帮助文档。
接下来，你需要把你的插件名称放在一长串的描述后面。有些作者（包括我）喜欢使用ASCII艺术字，来使得它变得更加有趣。添加一个不错的标题到potion.txt文件：
*potion.txt* functionality for the potion programming language
___ _ _ ~
/ _ \___ | |_(_) ___ _ __ ~
/ /_)/ _ \| __| |/ _ \| '_ \ ~
/ ___/ (_) | |_| | (_) | | | | ~
\/ \___/ \__|_|\___/|_| |_| ~
Functionality for the Potion programming language.
Includes syntax highlighting, code folding, and more!
我是通过`figlet -f ogre "Potion"
给Potion插件写文档。
阅读help help-writing了解一些关于写文档的帮助。
阅读:help :left，:help :right，以及:help :center来学习有关如何使用这三个命令来让你的ASCII字符排版的更有艺术感。
我是通过运行figlet -f ogre "Potion"来得到这些有趣的字符的。Figlet是一个很有用的用来生成ASCII艺术字的小工具。每行末尾的~字符是用来保证Vim不高亮或者隐藏艺术字内部的字符。
接下来一半都是目录。首先，我们来决定哪些需要写到文档里。
当给一个新插件写文档时，我一半都是按照下面的章节列表来编写：
如果插件比较大并且需要一个“概述”，那么我会写一个介绍的章节来概要说明一下插件的原理。否则的话，我会直接略过这部分。
一个“用法”章节需要介绍一下用户实际上如何使用你的插件。如果他们是通过映射来操作的，就告诉他们这个。如果映射不多的花，你可以直接列出来，否则的话，你就需要一个单独的“映射”章节来把它们给列出来。
“配置”章节应该列出所有的用户可以修改的配置项，并且告诉用户它们的作用以及默认值。
“许可证”章节应该告诉用户插件的代码所使用的许可证，并且有一个链接指向许可证的内容。不要再你的帮助文档里放许可证的全部内容 —— 大部分用户都知道常见的许可证，放在里面只会显得比较混乱。
“缺陷”章节应该简单明了。列出所有的你已经知道的并且还没有修复的缺陷，并且告诉用户如他们发现了问题，该如何告知你。
如果你想让用户能够提供修复缺陷的代码，或者添加新的功能，他们就需要知道如何去做。是在GitHub上发起一个pull request？或者是在Bitbucket上？还是在邮件里发出一个补丁？所有的还是前面任何一个都可以？添加一个“如何贡献”的章节来说明一下你更偏向于如何接受代码。
一个“更新日志”章节可以帮助用户很快地去了解当他从版本X升级到版本Y的时候放生了哪些变动。并且，我强烈推荐你使用一个类似Semantic Versioning版本表格来描述你的插件，并且坚持这样做。你的用户会感谢你的。
最后，我喜欢添加一个“贡献列表”章节，这里会提到我的名字，并且列出其他所有对这个插件有启发意义的插件，需要感谢的贡献者，等等。
这是一个很好的出发点。对于一个独一无二的插件，你会感觉到需要从这个列表出发，并且这样做非常好。写文档没有什么比较难或者比较快的法则，除了以下几条：
现在我们已经了解了我们会添加哪些章节，添加下面的内容到potion.txt文件里：
CONTENTS PotionContents
1. Usage ................ |PotionUsage|
2. Mappings ............. |PotionMappings|
3. License .............. |PotionLicense|
4. Bugs ................. |PotionBugs|
5. Contributing ......... |PotionContributing|
6. Changelog ............ |PotionChangelog|
7. Credits .............. |PotionCredits|
这里有一些东西需要注意。首先，由=组成的行会被语法高亮。你可以用这些行来分割你文档的不同章节。你也可以使用-组成的行来分割子章节。
这里的*PotionContents*会创建另外一个标签，所以你可以用:help PotionContents直接定位到帮助文档的目录。
每个被|所围住的字符创建了一个到标签的链接。用户可以把光标定位到帮助文档的目录了。
Vim会隐藏这些*和|字符，然后对它们进行语法高亮，所以最后显示出来的是一个其他人可以用来进行查找的很好看的一个目录。
你可以通过下面的方式来创建一个区块头：
Section 1: Usage PotionUsage
This plugin with automatically provide syntax highlighting for
Potion files (files ending in .pn).
It also...
请确保你通过*字符创建了正确地标签，这样你的目录里的所有链接都能正常工作。
继续给你的目录你的每个章节创建一个区块头。
我很想讲解一遍帮助文档的所有语法并且告诉你如何去使用它们，但是如何写帮助文档完全取决于个人的爱好。所以，我会给你一些有着很好文档的Vim插件作为示例。
对于每个产假，你可以把文档的源文件直接拷贝到你的Vim缓冲区，然后把它的文件类型设置为help来看看它会渲染成什么样的结果。当你想看具体是如何实现的时候，你可以通过切换回text的方式来查看。
你可以创建一个按键映射来创建一个可以把当前缓冲区的文件类型在在help和text之间进行切换的开关。
记住所有的Vim自身的文档都可以作为参考示例。你可以从中学习到很多。
现在你已经看过其他的插件是如何划分文档的结果，以及如何去写文档了。你可以开始给你的Potion插件写文档了。
如果你还不习惯写技术文档的花，那么这个对你而言可能就是一个挑战了。学习如何去写当然不是很简单，但是和其他许多技能一样，它只需要你去练习就可以了，所以直接开始写吧！你没必要写的非常完美，你以后可以一直来改善它。
不要害怕写一些你还不完全确定的东西，然后丢弃它们，最后再进行重写。经常在缓冲区放一些东西能够让你很快进入写的状态。如果你想回头再看看，它们还会留在版本控制里。
一个很好地开始的方式就是假设你有一个坐在你旁边的朋友，他也是在用Vim。他们没有哟过过你的插件，但是很感兴趣，你的目标是让他们变成使用你插件的专家。假设你是在给一个普通的人讲解，是一个很好地方式，它能够限制你在讲清楚整件事大体上是如何运作之前，不要变得太技术化。
如果你还是被卡住了，并且没有准备好为整个插件来编写文档，你可以尝试一些更小的东西。选择你的~/.vimrc里的一个映射，然后通过注释的方式提供完整的文档。解释一下它是用来干什么的，怎么使用，如何工作的。例如，以下是我自己的~/.vimrc文件：
" "Uppercase word" mapping.
"
" This mapping allows you to press in insert mode to convert the
" current word to uppercase. It's handy when you're writing names of
" constants and don't want to use Capslock.
"
" To use it you type the name of the constant in lowercase. While
" your cursor is at the end of the word, press to uppercase it,
" and then continue happily on your way:
"
" cursor
" v
" max_connections_allowed|
"
" MAX_CONNECTIONS_ALLOWED|
" ^
" cursor
"
" It works by exiting out of insert mode, recording the current cursor
" location in the z mark, using gUiw to uppercase inside the current
" word, moving back to the z mark, and entering insert mode again.
"
" Note that this will overwrite the contents of the z mark. I never
" use it, but if you do you'll probably want to use another mark.
inoremap mzgUiw`za
它比一个完整插件的文档要短的多，但是它是一个帮助你进行练习的一个很好的例子。如果你把~/.vimrc文件放到GitHub或者Bitbucket上的话，它也能够帮助别人去理解你的这个文件。