创建一个能工作的软件是件艰难的工作，需要时间、专业知识和经验。经过这一切艰苦的工作后，开发者最不愿意做的就是花时间去回答使用该软件的用户提出的“愚蠢”问题。避免大多数基本问题的最佳方法就是告诉用户如何使用该软件——提供文档！

我们都见过随程序一起下载的“readme.txt”文件。大多数用户都忽略了它，只有在无法理解自己应该做什么时才会打开它。在这个时候，文档变得最为重要——用户实际上正在寻找它！

文档之所以如此重要，是因为它是潜在用户在试图了解你的创造是如何工作时唯一可以求助的资源——如果你想避免问“你打开了吗？”，作为开发者你能做的最好的事情就是提供一些详细的关于如何操作的内容。

快速入门

如果你的应用程序像打开它并看着火花飞溅一样简单易用，就说出来吧！如果还有更多高级功能和功能可用，稍后再描述。大多数人不想花时间去翻阅关于“安装”、“配置”和“使用”的页面。直接告诉用户安装后需要启用这个，禁用那个。一旦这些事情都解决了，你就可以讨论更具体的细节。

安装101

不要假设每个人都知道如何安装Joomla！，如何将扩展安装到Joomla！，或者在你用户从数百个其他地方寻求安装扩展的提示中，他们会知道如何操作。描述安装过程，或者提供关于它的优质资源。

记录界面的功能

记住，假设用户知道他们不知道的事情，这是大多数开发者遇到支持问题时陷入困境的原因。告诉人们所有按钮、开关、下拉菜单和切换按钮的作用。一个出色的界面设计也能走很长的路，并使这个过程更容易。Brian Teeman，一位经验丰富的Joomla!实施者和项目联合创始人，在可用性主题上进行了撰写。具有文档功能的专家界面将给您更多时间进行开发，而回答简单支持票的时间会更少。

跳出你的同侪圈子

让另一个技术狂热的朋友审查你的文档并不能帮助你写出好的文档。他们很可能知道你在想什么，并能猜测你应用程序的流程。当我为Joomla文档团队写作时，我让我的弟弟——一个检查电子邮件都有困难的男孩——按照我写的步骤进行检查，看看它们是否有意义。我的文档细节得到了许多赞扬，我将其归功于他在遵循步骤时经常说“那是什么意思？”。

记住，“冗长”并不意味着详细——详细是精确和直接的。命令人们并给予真正的指导。

“一图胜千言”

包含有意义的截图。管理员区域的截图没有帮助——几个具体的控制面板按钮的截图，其中一个被圈出并标注，才是有用的。视频很棒，但对于想要快速浏览并找到他们正在寻找的确切内容的人来说，它有点困难，所以要小心。

记录演示

大多数人选择特定的扩展功能是因为他们看到了它做什么。他们想要的正是这个，而不是其他任何东西。告诉人们你使用哪些设置来获取你的演示（或者将那些设置作为演示数据包括在内，更好！）来做它所做的事情。由于你已经记录了每个设置，因此他们可以在不强迫他们弄清楚你所做的情况下更容易地进行自定义设置。

故障排除技巧

如果你发现你在某个特定的问题上收到了很多支持请求，阅读你自己的文档。你是否确定了人们正在处理的具体情况？添加一个故障排除技巧部分，并在需要时添加。记住，这同样是为了帮助你，就像它是为了帮助你的用户一样。支持时间更少意味着开发时间更多，并且少了几缕白发。

多语言

如果你能够提供多语言文档，那么就做吧！Joomla!领域是全球性的，用另一种语言提供你的文档将进一步促进这个生态系统。

我认为听取支持一些非常复杂Joomla!组件的开发者对文档的看法将是一个重要的贡献。所以我与我的同事Nicholas Dionysopoulos进行了交谈，他提供了以下建议

人们讨厌阅读

仅仅因为你写了文档，并不意味着每个人都将阅读它。准备好回答那些已经在文档中回答过的问题。如果你有一个支持票系统或论坛，你会看到一种模式的演变。每天都会出现10-15个相同的问题。利用这个知识来制作知识库/故障排除指南。如果你实际上根据他们试图解决的问题将人们重定向到你的文档中的特定页面，而不是在另一份文档中复述你的文档，你将获得额外的加分。

人们喜欢观看

没有人会阅读两页的“入门指南”，即使你付给他们钱。然而，几乎所有的人都会乐意观看一个包含相同内容的5分钟视频教程。制作屏幕录制视频相当简单。如果你在电脑上工作时感到不舒服，就写一个脚本（就像电影脚本一样！），练习并录制它。或者，录制屏幕录制视频，并让一个英语更自信的人来做配音。如果你能说服一个声音友好的女友好心为你做配音，你还能得到额外的加分。

“病人都在撒谎”——格雷格·豪斯博士

人们经常会告诉你他们已经阅读了文档，但他们有这个问题或那个问题。不要假设因为他们这么说，就是这样的。很可能是他们浏览了文档，但错过了描述解决他们具体问题的段落。如果你怀疑是这样的情况，不要害怕将他们链接到你的文档，或者如果你怀疑是这样的情况，就改写一小段内容。这就是优秀的支持与其它支持的区别：能够将用户指向文档的正确段落。

单源多格式

在线文档只有在您始终在线的情况下才有用。不要假设因为大多数西方人24/7都连接到互联网，这就意味着在世界上所有地方都是这种情况或对所有用户来说都是可能的。有些国家没有宽带服务，连接速度慢且费用高。在其他情况下，用户不可能始终在线。这些人除非你提供离线友好的格式（例如PDF），否则不会使用文档。确保这一点的最佳方法是将你的文档写入合适的格式，例如DocBook XML格式，然后从这个单一来源生成在线和离线版本。