记录 WordPress 插件和主题

已发表: 2017-03-17

文档通常只有在出现问题并且您需要快速回答时才会受到赞赏。在本文中，我们将介绍为什么为您的 WordPress 资产编写文档对于您作为 WordPress 开发人员的实践以及您发布的主题和插件的质量很重要的原因。

为什么文档很重要？

出于多种原因，保持有关您的项目、资产或产品的最新文档集很重要。

首先，看到你 2 个月前制作的东西并且从那以后没有接触过的东西，并且不知道它意味着什么，这是一种常见的体验。当你开发它时，你的脑子里已经有了它，但这种理解在未来不会存在。因此，无论是使用内联代码注释还是在 Markdown 中编写纯文本注释，都可以大大帮助您将来避免混淆。

其次，将您的资产记录在案对其他 WordPress 开发人员很有帮助。即使你是一个孤独的自由职业者，这也是有道理的（你一定会在某些时候与其他人合作）。他们要么需要使用这些资产，要么被要求维护和/或更新它们。不得不使用由其他人编写的未记录的代码非常令人沮丧，他们不在身边提供支持或解释一些困难的部分。

最后，文档为您的产品添加了“抛光”外观，您的客户会更爱您。

技术写作本身就是一门学科，它用于以清晰明确的方式传达技术信息。（不仅限于计算机，例如律师和医生，也使用他们自己的技术语言）。出于这个原因，被认为是技术写作的文档通常遵循某种风格并遵守一套规则。

让我们来看看最重要的 5 个，这样您就可以为您的产品编写有效的文档！

喜欢使用比您通常在写作中使用的更少的单词：每个单词都应该有一个目的。直接和简单。当一个人遇到麻烦并想要快速找到解决方案时，通常会寻求文档。例如，“无法销毁对象 Q将导致内存泄漏”这样的句子比“无法销毁对象 Q将导致内存泄漏”更可取。
更喜欢使用主动语态而不是被动语态：“单击右上角的按钮”而不是“需要单击右上角的按钮”。使用主动语态可以消除关于谁做什么的任何歧义。被动语态仅在您需要关注对象而不是主题时使用（例如， Pressidium 的平台是在考虑安全性的情况下构建的）。
当您需要描述概念时使用描述性语言，当您需要描述分步过程（如教程）时使用命令式语言。
当您需要列出没有顺序的事物时使用项目符号列表，当要点的顺序很重要时使用编号列表。
在演示之前，请确保您自己测试了这些说明！

WordPress 插件就像任何其他软件一样。它们提供一定的功能，需要安装，有时还需要故障排除。无论它们多么简单，提供足够数量的文档总是一个好主意，因为并非所有用户都拥有相同的技术专长。

在 wordpress.org 上发布您的 WordPress 插件将为您提供一个放置安装说明、屏幕截图、常见问题解答甚至更新日志的地方！用有用和高质量的信息填充它们是使您的插件变得更受欢迎的关键：

如果您遇到困难并需要一些灵感，请进行一项小型研究，看看文本是如何在拥有数十万安装的流行插件中编写的，与较少使用的插件相比。

记录 WordPress 主题完全是另一回事。 WordPress 主题最常见的问题是不知道哪个部分对应于哪个视觉元素。不是每个人都精通 CSS：

创建 CSS 的所有部分的层次结构，并带有相应的描述。
对于每个部分，添加一个带注释的屏幕截图，详细说明每个功能，以及一个小示例。在展示如何做需要用户遵循说明的事情时，不要忘记使用主动语态和命令式语言。
使用诸如 css_doc 之类的工具来帮助您。这会生成 JavaDoc 样式的文档并且可以发布。
有时代码注释是不够的，你需要为你的 CSS 主题创建一个样式指南文档。样式指南文档描述了元素的外观以及在什么情况下需要使用它们。它们强制一致性并使协作更容易。请参阅 Google 提供的此示例。
使用像 Blueprint CSS 这样的 CSS 框架。这将通过为您提供一组工具来帮助您进行开发，例如可自定义的网格、有效的默认排版、浏览器 CSS 重置等等。
同样，不要忘记查阅官方的 WordPress CSS 编码标准。