开发文档工具_您的文档是您开发工具的门户-CSDN博客

开发文档工具

编写好的文档至关重要。在Appwrite上工作时，文档是我们开发生命周期的重要组成部分之一。当我们构建为开发人员设计的工具时，我们的文档是开发人员首次与我们见面的地方。即使您的产品很棒，复杂，不清晰或无组织的文档站点也会使开发人员离开。如果您的代码很棒，或者没有人可以使用它，那么它并没有多大用处。

有了这些想法，我们就设置了有关文档站点开发的规则。对我们而言，构建开发人员会喜欢并且易于使用和理解的文档非常重要。在这篇文章中，我将尽我最大的努力来分享我们提出的一些原则，同时尝试以与对待正常源代码相同的耐心和奉献精神来对待我们的文档。

当开发人员尝试深入研究您的文档时，您的设计是第一眼。实际上，这是他们甚至在阅读您编写的一行文本之前就看到的第一件事。

您不必一定要成为设计专家，但是可以确保您的文本格式清晰干净。使用具有良好对比度的颜色，足够的间距并确保字体可读。验证您的设计是否符合W3C可访问性准则总是很高兴的。

深色模式也是开发人员高度赞赏的功能，特别是如果他们喜欢穿深色运动衫并坐在黑暗中时:)。

想一想用户从项目中获得价值所必须采取的最必要且不可跳过的步骤。我喜欢计算完成每个动作并尝试优化该步骤所需的步骤数。

请记住，您的文档应满足开发人员首次检查您的项目以及每天处理该项目的需求。找到正确的平衡至关重要。

一些开发项目可能针对不同类型的开发人员。为不同的目标受众很好地分离内容。例如，对于不同的开发平台，我们具有不同的集成。

我们具有针对Web，移动，本地和后端开发人员的集成。每个受众都有自己的入门指南和路径。我们尝试要求最少的初步知识，以尽可能地使我们的学习曲线保持一致。

标题和链接锚点是组织数据的好方法。锚点将帮助开发人员轻松共享您的内容，标题将使已经在与您的项目一起工作的开发人员能够准确跳到他们最后一次访问文档时留下的地步。

不要指望别人像您一样理解您的产品。开发人员的时间很宝贵。在每个阶段或教程的最后，请考虑什么是您的用户最好的下一步。始终想一想如何帮助您指导他们完成完美的流程，以掌握您的工具。这可以是另一个文档，部分，甚至可能是一些相关的外部资源。与其他所有产品一样，请尝试采取措施并帮助您的用户完成多个步骤。

同样，开发人员的时间很宝贵。不要浪费它。许多开发人员通常会尝试跳过您的长文本，直接跳到您的代码示例中以节省时间，并找出您的项目是否与他们相关。

确保流程中的每个步骤都有大量示例。确保示例简单且简短。没有人愿意开始调试您的300行代码或浪费15分钟来找到一个功能。您开发了一种供开发人员使用的工具，其目的可能是节省一些时间。编写复杂的代码示例将做相反的事情。

编写具有凝聚力的代码示例，并让每个示例都实现一个目标。链接到完整的工作脚本也很不错，以防您的代码示例彼此高度依赖。您可以将完整的脚本托管在GitHub或Codepen等第三方网站上，以简化文档。

开发人员很聪明，请像这样对待他们。我编写代码已有20多年了，我不喜欢周围发生魔术。我确实想了解我使用的工具中正在发生的事情。我不一定要了解每一个细节，但我希望对概念进行基本的轻描淡写。使代码开源是获得透明度和信任的一种好方法。另一个是共享有关您的体系结构，工具堆栈和设计折衷的信息。

在Appwrite上，我们的源代码可在GitHub上获得，我们的设计规范在我们的仓库中进行了说明，我们的工具堆栈在stackshare.io上共享。

朴素为王。这个词对软件和内容都适用。确保您的文档简单，不需要大量的学习曲线或可以避免的初步知识。有一节专门介绍高级主题，或者至少确保不要将初学者和忍者级开发人员的内容混在一起。避免在开始时就扔重枪。

您的文档永远不会是完美的。这可能是由于时间不足，缺乏对受众群体的初步了解或产品多次转向所致。不管原因是什么，只要您了解就可以，并且您一直在努力改进它们。

与您的社区交谈，提出并回答问题，始终存有疑问，并问自己自己可以做些什么来更好地避免用户问题。您虽然无法保持凝聚力，却无法同时回答每个问题，但是您始终可以努力改善并寻求更好的平衡。

结论

编写文档不如编写代码那么有趣，但是它确实很重要。您的文档是开发人员将满足您的项目并决定是否满足其需求的地方。优质的文档可以像优质的源代码或优质的API一样帮助您更快地编写软件。您绝对应该花时间来（几乎）完美地构造文档。

Appwrite是由社区驱动的开源后端服务器。您可以通过访问Appwrite 官方网站或Github存储库了解有关Appwrite功能，API和集成的更多信息。您还可以在我们的Twitter或Facebook帐户上关注Appwrite新闻和公告。您也可以在我们的Discord服务器上与我们聊天。

我叫Eldad Fux。我是一位企业家，软件架构师，对开源热衷并且是appwrite.io的创建者。您可以通过我的Twitter帐户关注我： https ： //twitter.com/eldadfux或通过Linkedin与我联系： https : //www.linkedin.com/in/eldadfux/ 。