编写第一个软件文档的指南

作为开发人员，您的骄傲和喜悦是您的代码。它是可读的，符合干燥原则，反映了最佳实践，最终产品是一个很好的工具，可以解决其目标用户的某种问题。但是，无论您在代码中投入了多少工作，如果您的软件没有文档，或者您将文档作为事后思考，并且对其进行了很少的重视处理，那么用户可能会很少能找到使用它的乐趣，并且最终选择了不同的，更易于用户友好的产品。

>在本文中，您会发现许多实用的指导原则，可以通过编写第一个软件文档来启动并运行。

钥匙要点

• 好的软件文档对于用户采用和理解至关重要，它是开发人员和用户之间的通信工具。它应包括教程，操作指南，参考指南和说明，为软件功能提供全面的指南。
>
• 应清楚地识别用于文档的目标受众，因为这将塑造所使用的内容和语言。在本指南的背景下，重点是针对对软件熟悉的开发人员的文档，而不是用户手册或项目文档。
• >文档应易于发现，结构良好并定期更新。建议将文档保持在源控制中，以确保在发生代码更新时保持相关和准确。包括常见问题解答页面还可以帮助解决常见的用户查询。
• 除了传统文档之外，博客文章可以用作解释软件功能，提供教程和共享更新的有用工具。这可以培养围绕软件的社区，从而有助于其增长和成功。良好的文档实践的示例可以在诸如Greensock，React和Vue.js.
等平台中找到。

为什么文档很重要

>

参考您的软件，Mike Pope有一个合适的说法：如果没有记录，则不存在。

为什么？ 好吧，只是以我的个人经验为例，我正在浏览网络，以寻找新的JavaScript动画库来尝试，我遇到了一个我真正喜欢的功能的描述。但是，没有文档，甚至没有入门部分，而只是一个裸露的API页面，几乎没有解释或示例。您认为我最终使用了该库吗？当然，我没有。我对此感到非常沮丧，以至于我继续对自己更有意义的事情。

>

的问题为什么好的javascript库失败，nicholos zakas给出了以下答案：

缺乏文档。无论您的图书馆多么美妙以及它的设计多么聪明，如果您是唯一了解它的人，它都不会有任何好处。文档不仅意味着自动化的API参考，还意味着注释的示例和深入的教程。您需要所有这三个，以确保您的库可以轻松地采用。

>您的软件文档至关重要的另一个重要原因是它们是您当前的自我和未来自我之间以及当前自我与其他开发人员之间的交流工具，这些工具最终可能会发现自己从事您的软件。即使您编写可读和评论的代码，这并不一定意味着您仍然会在六个月的时间内清楚您为什么写函数或以此为代码的任何其他代码。

>文档允许您在代码背后传输为什么。以相同的方式，代码注释解释了为什么，而不是>>，文档的目的相同。 - 撰写文档的初学者指南>

>当然，您希望人们使用您的代码，并最终能够对其进行更新并改进它。这些都是为您的产品背后的支持社区增长的重要因素，这对于获得稳健性，成熟度和成功很重要。

> 如果您的软件没有很好的文档可以使用。

谁软件文档适用于

>

撰写任何内容时，请确保您的听众是谁。文档也不例外。这样做会阐明您的观众可能面临的问题，这可能对您的产品或使用产品的先决条件。此信息对于您创建内容和使用的语言的方式至关重要。

>

有两种文档本文不关心：

>

1. >用户手册。例如，我姐姐可能决定使用WordPress发布自己的博客。她不是开发人员，但听说非Devs可以随时与WordPress一起启动并运行他们的博客。现在，她将需要有关如何在服务器上下载和配置软件的说明手册。
2. >项目文档。这种文档与项目本身的关系更多，尽管它的某些内容可能会在项目的README文件中进行。为了继续进行WordPress示例，在使用WordPress进行了大量练习之后，我可能会决定要在软件中添加功能或修复一个或两个错误。在这种情况下，我需要了解诸如变更，惯例和最佳实践，贡献政策，如何参与与手头任务相关的团队讨论等的事情等。

>我在这里想到的文档类型主要是针对对您的软件熟悉并且需要在项目中使用它的开发人员。例如，如果我要创建一个WordPress主题，那么我需要知道如何开始，如何包括样式表和JavaScript文档，如何与数据库进行通信以显示帖子等。

在您的文档中包含什么

>一种流行的方法是由汤姆·普雷斯顿·妻子（Tom Preston-Werner）倡导的README驱动开发。它包括在开始编写任何代码之前编写readme文档。该文档是对您软件的介绍，通常包括：

>

>对您的软件的功能以及它解决的问题的解释

>
• 一个示例说明通常使用代码的情况
>
• >链接到代码和错误跟踪器
• 常见问题解答和寻求支持的方法
• >有关如何安装软件的说明
• >许可信息
• 但是，在我看来，拥有一个可靠的文档，可以真正帮助使用您的软件/库的开发人员远远超出经典的读数文件。在Daniele Procida之后，我建议您在文档材料中包括以下项目以获得出色的用户体验。
>教程

初学者会喜欢在您的软件文档中找到一个教程。教程旨在向用户展示如何使用您的软件完成项目，以便他们可以快速了解自己可以做的事情。

>

>教程是

课程

，可以将读者借助一系列步骤完成某种项目。它们是您的项目所需的，以便向初学者展示他们可以通过它实现的目标。 -

daniele procida

操作方法指南

操作方法指南可帮助用户使用软件解决现实世界任务。 Procida将它们与食谱进行了比较，因为它们是您给用户提供的方向，以便他们可以成功实现某个目标。与针对完整初学者的教程不同，如何指导用户已经拥有一些对功能，工具以及如何执行简单任务的基本知识。

参考指南

参考指南是您软件代码的技术参考 - 功能，API等 - 并提供有关如何使用软件的基本描述。例如，您会找到一个说明，说明如何实例化特定类，如何调用特定方法等等。

参考指南是机械的技术描述，以及如何操作它。 -

daniele procida

>这是您在大多数项目中可能会找到的文档。开发人员倾向于编写它，因为他们对自己的代码了解全部了解。 >说明

的解释是您认为与您对软件的高层理解有关的特定主题的深入研究或讨论。关于解释，Procida指出 -

这部分文档很少是明确创建的，而是在其他部分中分散了解释的片段。有时，该部分存在，但有一个名称，例如

>背景或其他注释

，并且并不能真正对该功能公正。

>

>主题不是由您要完成的特定任务（例如如何指南）或您希望用户学习的内容（例如教程）来定义的。它不是由参考材料而定义的。它的定义是由您认为是一个合理的领域，以便

>>>>

一次，因此讨论的主题有时可能是任意的。>

您需要注意的事情

> >让我们浏览一些有用的指针，以使您的文档用户友好且相关。 使您的文档可发现

>

>最好让您易于找到软件文档。您可以将某些SEO技术与某些营销策略一起使用，以便尽可能多的用户可以掌握它。

>

>此外，您将文档放入的内容也应组织成使搜索特定信息变得轻而易举的结构。 Steve Konves建议您将文档构造在单个链接的树上：从根节点开始，该基因应放置在一个明显的位置，供每个感兴趣的用户发现，所有其他项目都可以轻松访问。该项目的README文件可以使整个树的出色根节点非常有效。>

>另外，如果您从软件用户收到帮助请求，则可以编写答案并使它们在易于访问的常见问题解答页面中提供。这样做会减少您花费帮助用户的时间，但这也将使您更清楚地了解用户最常需要的信息类型，以便您可以先记录下来并将它们保持在文档中的突出位置。

确保您的文档是最新的，并且没有错误

>轻松访问您的软件文档非常好，但是如果用户发现其内容已过时，或者示例代码或指令会导致错误结果，那么至少可以说这会令人沮丧。尽管如此，史蒂夫·康维斯（Steve Konves）建议您将文档保持在代码附近，例如，在源控制中。这样，当开发人员更新代码时，他们会注意到文档材料，这使更新文档的更新更有可能发生。

>另外，要最大程度地减少错误的发生，请彻底测试您在文档中提供的说明和代码样本。

额外的提示和一些流行的示例

不要停止文档。博客文章非常适合使您的软件及其功能受到广泛的潜在用户的了解。使用您的博客来澄清您的产品的作用，提供用户友好的教程，提示和技巧，演练，解释更新等。您可以在专门用于软件的独立网站中包含您的博客 - 也许与论坛 - 一个强大的社区可以聚集和成长。

在我看来，这个更广泛的文档概念的一个很好的例子是由广泛成功的JS动画平台Greensock实现的，我发现自己使用了很多，尤其是因为它的网站使其易于使用且易于使用且易于使用结构化文档，一个超级有用的论坛，博客文章，快速提示等等。

>

react和vue.js也可以算作很棒的例子。一旦您访问了他们各自的网站，主页就会告诉您每个库在快速标语中有益于什么，然后详细介绍为什么库可以将其视为您项目的绝佳选择。这两个网站都可以使用柔和的介绍，说明性片段，简短的任务开始使用代码操场等工作。详细说明如何获得帮助，在生态系统上显示信息，提供新闻或博客部分等。

>

>离开JS区域，进入具有出色网站的流行UI库领域，我无法遗漏Bootstrap。在Bootstrap网站上，您会立即找到图书馆的用途以及如何快速入门，以及全面且结构良好的文档和博客，以使用户对新事物的最新信息保持最新。

结论

>编写良好的文档有其挑战，但是如果您认为用户可以实现软件功能要容易得多，它肯定会付出一百倍。反过来，这有助于您的软件的受欢迎程度，这使其具有吸引力，因此有可能引起一个愿意花费时间深入学习的开发人员社区，并为其增长，稳定和长期做出贡献用法。

经常询问有关编写软件文档的问题（常见问题解答）

>编写软件文档时要考虑的关键要素是什么？

在编写软件文档时，要考虑目标受众，文档的目的以及编写文档的类型至关重要。所使用的语言应清晰，简洁且易于理解。该文档的结构良好，并具有逻辑信息流。在必要的情况下，包括图表或屏幕截图之类的视觉效果也很重要。最后，始终确保对文档进行彻底审核和编辑，以进行准确性和清晰度。

>如何使我的软件文档对用户友好？

使您的软件文档用户友好，请使用简单和清晰的语言。尽可能避免行话和技术术语。如果您必须使用它们，请确保您提供明确的定义。逻辑地组织您的内容，并使用标题和子标题使其易于浏览。包括一张目录和一个较长文档的索引。使用图表，屏幕截图和视频之类的视觉效果来说明复杂的概念。

>有哪些不同类型的软件文档？

>

有几种类型的软件文档，包括系统文档，用户文档，用户文档，用户文档，和技术文档。系统文档提供了软件系统的概述，包括其架构和数据流。用户文档提供了有关如何使用软件并包含用户手册和帮助指南的说明。技术文档旨在为开发人员提供，并包括代码注释，API文档和开发指南。

>应更新软件文档？软件。这可能是由于添加了新功能，已修改现有功能或修复错误。定期审查文档以确保其仍然准确和相关也是一个好主意。

>

我可以使用哪些工具来编写软件文档？

>有许多用于编写软件文档的工具，包括文字处理器，文档生成器和专用文档工具。一些流行的选项包括Microsoft Word，Google Docs，Doxygen和Sphinx。工具的选择取决于您的特定需求和软件的复杂性。

如何确保软件文档的质量？

确保软件文档的质量，始终查看并彻底编辑您的工作。考虑让同事或专业编辑审查您的文档。在整个文档中使用一致的样式和格式。确保信息准确，最新和相关。最后，考虑从用户那里获取反馈以确定改进领域。

>视觉效果在软件文档中的作用是什么？

视觉效果在软件文档中起着至关重要的作用。他们可以帮助说明复杂的概念，从而更容易理解。它们还可以分解大量文本，使文档更可读。视觉效果的示例包括图表，屏幕截图，流程图和视频。

>如何使我的软件文档更具吸引力？

使您的软件文档更具吸引力，使用对话性音调和主动语音。用视觉效果和子弹点分解大块文本。使用示例和案例研究来说明概念。在适当的情况下包含交互式元素，例如测验或练习。

在软件文档中一致性的重要性是什么？

一致性在软件文档中很重要，因为它使文档更易于阅读和理解。它还使文档具有专业的外观。一致性适用于语言，样式，格式和视觉效果。

>我如何提高我编写软件文档的技能？

以提高您在编写软件文档，定期练习写作方面的技能。阅读其他软件文档以向它们学习。参加有关技术写作的课程或讲习班。寻求有关您的工作的反馈，并接受批评。在软件文档中的最新趋势和最佳实践保持最新状态。

>

以上是编写第一个软件文档的指南的详细内容。更多信息请关注PHP中文网其他相关文章！