大多数软件包都需要某种形式的注解,以帮助用户获得最佳体验并优化其使用。本页面提供了一些有关如何结构化信息和格式化文档提示。
在软件包的标题之后,您应为软件包的功能和/或它包含的内容提供基本的概述。在概述之后,包括安装说明以及任何系统要求和/或限制。您还可以提供获取帮助和提供反馈的链接,包括公共论坛或知识库以及帮助中心联系人。
在获得这些初步信息之后,您可以提供更深入的工作流程、用户界面描述或示例目录列表,以及更高级的主题。最好在最后提供参考页。
部分 | 描述 |
---|---|
概述 | 提供该软件包的简要、高层次的描述。 |
软件包内容 | 包括您希望用户知道的重要文件的位置。例如,如果这是一个示例包,各个示例分别包含了纹理、模型和材质,您可能需要提供每个组的文件夹位置。 |
安装说明 | 您可以提供指向官方的 Package Manager 安装说明的链接,但是如果您有任何特殊的安装需求,比如安装示例,可以在这里添加。 |
要求 | 这是添加硬件或软件要求合适的位置,包括此软件包与哪些版本的 Unity 编辑器兼容。 |
限制 | 如果您的软件包有任何已知限制,可在此处列出。如果没有限制,或者限制是微不足道的,可去除此部分。 |
工作流程 | 包括用户可以轻松遵循的步骤列表,以演示如何使用该功能。您可以包含屏幕截图来帮助描述如何使用该功能。 |
高级主题 | 您可以在此处提供有关要向用户提供的内容的详细信息。如果您不希望用户一开始就面对太多信息,这是理想的选择。 |
参考 | 如果您的用户界面具有很多属性,则可以在参考部分中提供详细信息。使用表格是快速访问特定属性描述的好方法。 |
示例 | 对于包含示例文件的软件包,您可以包含有关用户如何在其项目和场景中使用这些示例文件的详细信息。 |
教程 | 如果您想为复杂程序提供演练,您也可以在此处添加。使用分步说明,并包含可以帮助用户理解的图像。 |
Markdown 是一种软件包中常用的轻量级格式。许多代码仓库托管服务(例如 GitHub 和 Bitbucket)都支持该格式的自述文件和文档站点。您可以在软件包根目录下的“Documentation~”文件夹中提供一个 MD 文件,用户在 Unity Package Manager 的详细信息窗格中单击 View documentation 的链接时,默认 MD 查看器将打开该文件。
或者,您可以使用自己的网站来托管您的文档。要将 View documentation 链接的位置指向您自己的网站,请在您的 package.json
文件中使用 documentationUrl 属性进行设置。
如果您决定使用 Markdown 文件为您的软件包撰写文档,您可以从众多帮助站点找到有关如何编写 MD 文件的更多信息,例如:
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.