在移动、web和桌面应用或JavaScript库的开发领域，文档在决定应用的成功中扮演着重要的角色。但是如果您曾经做过文档，您会同意我的观点，那就是文档是开发人员最不喜欢做的事情。
与编写代码(这是开发人员签约时要做的事情)不同，文档必须容易被每个人消化。从技术上讲，我们必须把机器语言(代码)翻译成人类可以理解的语言，这比听起来要困难得多。
尽管编写文档真的很麻烦，但它很重要，它将为您的用户、您的同事，特别是您自己带来好处。
良好的文档有助于用户
显然，文档可以帮助读者理解代码是如何工作的。但是许多开发人员错误地认为软件的用户都是精通的。
因此，文档可能是很薄的材料，跳过了很多从一开始就应该包含的基本内容。如果你精通这门语言，你就能主动把事情搞清楚;如果你没有，那么你就迷失了。
为用户准备的文档通常包括实际使用或“如何”。在为普通用户创建文档时，经验法则是它应该是清晰的。使用对人友好的词语比使用技术术语或行话更可取。也将非常感谢真实的使用例子。
一个好的布局设计也能真正帮助用户浏览文档的每个部分，而不会使眼睛疲劳。一些很好的例子(也就是我最喜欢的)是Bootstrap文档和WordPress的“使用WordPress的第一步”。
它可以帮助其他开发者
每个开发人员都有自己的编码风格。但是，当涉及到团队工作时，我们经常不得不与其他队友分享代码。因此，有必要在一个标准上达成共识，以保持每个人在同一页。一个适当的书面文档将是团队需要的参考
但与最终用户文档不同的是，该文档通常描述技术过程，如代码命名约定，展示如何构造特定页面，以及API如何与代码示例一起工作。通常，我们还必须编写与代码(称为注释)内联的文档，以描述代码正在做什么。
此外，在你的团队有新成员加入的情况下，这个文档可以是一种有效的培训他们的方法，所以你不必让他们1对1地运行代码。
它也能帮助程序员自己
关于编码的有趣之处在于，有时甚至开发人员自己也不理解他们所编写的代码。这在那些密码几个月甚至几年都没被碰过的情况下尤其正确。
突然出于某种原因需要重新访问这些代码会让人想知道在他们编写这些代码时脑子里在想什么。别惊讶，我以前也遇到过这种情况。正是在这个时候，我希望我正确地记录了我的代码。
通过编写代码文档，您将能够快速地了解代码的底层，而不会感到沮丧，从而为您节省了大量可以用于完成更改的时间。
什么是好的文档?
有几个因素可以帮助构建一个好的文档。以下是一些最重要的问题:
1. 永远不要认为
不要以为你的用户既知道你知道什么，也知道他们想知道什么。不管用户的熟练程度如何，从头开始总是比较好。
例如，如果您构建了一个jQuery插件，您可以从SlickJS的文档中获得灵感。它展示了如何构造HTML，在哪里放置CSS和JavaScript，如何在最基本的级别初始化jQuery插件，甚至显示添加所有这些东西后的完整最终标记，这是显而易见的。
最重要的是，文档是以用户的思维过程而不是开发人员的思维过程来编写的。用这种方式来处理你自己的文档会让你在组织你自己的作品时有一个更好的视角。
2. 遵循标准的
在添加与代码内联的文档时，使用语言所期望的标准。描述每个函数、变量以及函数返回的值总是一个好主意。下面是一个很好的PHP内联文档示例。
以下是一些使用PHP, JavaScript和CSS的最佳实践来格式化内联文档的参考:
WordPress的PHP文档标准
如果你正在使用SublimeText，我建议安装DocBlockr，它将巧妙地用内联文档预填充你的代码。
3.图形元素
使用图形元素，它们比文本更好地表达。这些媒体非常有用，特别是当你构建带有图形界面的软件时。您可以添加指向元素，如箭头、圆或任何可以帮助用户确定在何处完成这些步骤的元素，而无需猜测。
以下是来自Tower应用的一个例子，你可以从中获得灵感。它们有效地解释了版本控制是如何以一种令人愉快的方式工作的，这使得它比使用纯文本命令行更容易理解。
4. 切片
您可以考虑将文档中的一些内容包装在项目符号列表和表格中，这样可以使用户更容易浏览和阅读较长的内容。
添加一个内容表，并将文档分成容易理解的部分，但要保持每个部分与接下来的内容相关。保持简洁明了。下面是一个很好的Facebook文档组织的例子。目录表带我们去哪里，我们想跳跃到点击。
5. 修改和更新
最后，检查文档中的错误，并在必要时或者在产品、软件或库发生重大变化时进行修改。如果您的文档不定期与您的产品一起更新，那么它对任何人来说都是毫无用处的。
