好的，这可能有点像#humblebrag，但是我想写这个故事有一个很重要的原因，一个原因强调了受过训练的，熟练的技术作家创造可读性，组织性和有用性的价值。内容。
昨晚我以科技作家@ Wikimedia Foundation的身份参加了“为开源贡献的编写文档SF”聚会 。 聚会包括一个动手部分，我们分成几个小组，解决了MediaWiki的一些小内容需求。
我最后一个小组选择了更新图标和小部件图形的任务，因为MediaWiki已从Apex主题过渡到MediaWiki主题。 我们确定文章中实际使用图形可能不是最好的主意，而是链接到主题源的链接更好，该主题源显示了实际图形并进行了更新。
在阅读文章介绍时 ，我发现了我认为的几个问题。 这是我开始工作之前的样子：
这是我写的新版本：
在开始之前，请先声明一下。 在对原著进行批判时，我绝不想在我发现这部分内容之前就贬低为这些内容做出贡献的作者的知识，技能和热情。 我在WikiMedia上遇到的几个人都是（虽然有点初学者刻板印象）年轻，朝气蓬勃，非常非常聪明的人。
但是他们不是作家。 更具体地说，他们不是技术作家。 问题就在这里，不仅在这里，而且在很多其他地方，对透明内容的需求非常迫切。
第一步是了解谁是该内容的读者（或消费者）。 这是程序员的内容。 程序员有自己的语言和专业术语，可以自由使用，因此此处使用正确的专业术语是可以的。 程序员也不需要解释很多基本概念，并且实际上，如果您开始用少量易消化的内容向他们喂食内容，那么他们可能会轻视内容。 最后，程序员很忙。 他们想进入，得到他们所需要的，然后离开。
下一步是查看其中的信息。 重要的是什么？ 什么不重要？ 有什么关系？ 有什么关系？
考虑诸如此类的问题后，我确定现有内容中存在一些可以纠正的问题。
本部分内容的主题是关于按钮小部件。 对我来说，最初的主句不仅不够明确，而且添加了一个短语，使人无所适从。 因此，我做了一个简短的句子来开始简短，基本，直接和切题的部分。 它是本节中所有其他内容的基础。
第二句话是一个承诺，我将在下一部分中兑现这一承诺。 它没有提供具体的信息，但确实会导致随后发生的一切。 以上就是第一段。
下一段给出了阅读读者所需的第一部分更具体的信息。 请注意突出显示关键部分的格式。 这对于内容扫描仪是必需的。
然后将线索导入项目符号列表。 每个项目符号提供了可用子类型的简短说明。 我进入项目符号列表的方式使我可以在每个项目符号的开头添加突出显示（一个子类型可以具有两个不同的子类，但该子类型除外），从而可以轻松地扫描该内容。
每个项目符号都具有平行的结构，以便始终如一地呈现信息。
最后一段是不太重要的信息，最初埋在较大的开头段落中。
我摆脱了副词，使内容的确定性降低。 我摆脱了引号，并使用格式使选项脱颖而出。
结果是一个更好地组织，更易读和更可扫描的简介。 这样可以轻松找到那里的信息。 导航到该页面的任何人都可以快速轻松地了解他们是否在正确的位置，以及如果进一步阅读就会发现什么。
