有关文档编制的50个问题

无论UX设计人员多么努力，街上的人们都无法在没有提示的情况下弄清楚航天器的控制界面。 甚至不在街上。 仅仅因为火箭很大而且设置很多。

我们使产品比用于火箭的软件更简单，但技术上仍然很复杂。 我们尽力使新版本的界面变得简单，但是我们意识到总会有一些用户不了解某些内容，因此请查阅文档。 因此，应该有一个底座，并且为了不破坏产品的外观，它应该是有用且方便的。

我们有六种产品，这些文档是公司的基础，由开发人员编写。 半年以来，我们一直在重写旧 文章和写新文章 。 减少开支-可以帮助我们做到这一点的50个问题。 但是首先，有一些介绍。

为什么文件很重要，谁应该做

建立一个好的码头是很难的。 某个地方有庞大的分析师，作家和编辑部门在进行此工作，而某个地方的开发人员正在向Dock进行写（完成-描述）。

我们有六个产品的多个版本的两位技术作家。 这还不够，因此产品经理，测试人员，第一线支持和市场营销工作就在码头上。 他们不写文章，但有助于理解客户的产品和任务，选择主题并收集信息，检查完成文章的内容和设计。 我们在一起使码头变得更好。

如果您有一个小型的技术撰稿人部门，请从其他部门招聘人员。 如果他们不感兴趣，请从下面的列表中提供参数。 第一支持，第二和第三营销以及产品营销。 那么，文档为何如此重要？

1. 支持因素 。 第一个也是最明显的原因。 如果文档很好，大多数客户将解决此问题而无需联系支持。 其余的支持将提供指向说明的链接，或者自己快速查看。 完整的文档可用于创建聊天机器人。 所有这些减少了对客户的响应时间，提高了客户满意度，还降低了支持成本。
2. 选择因子 。 文档会影响客户的选择以及价格，便利性和功能。 我们的研究和ISPmanager和DCImanager用户的反馈都证实了这一点。 从这个角度来看，扩展坞不再是必需的支持，而是成为竞争优势（营销的一部分）。
3. 忠诚度因素 。 如果客户在开始时或过程中不了解扩展坞而离开，这就是一个问题。 吸引顾客实在是太昂贵了，以至于因为物品不好而流失。

如何做好文件

定义一个目标 。 这是最痛苦的。 仅仅为了描述或对接口进行注释而描述功能并不是目的。 目标永远是有益的行动。 用户，管理员或开发人员在阅读文章后应了解什么并能够阅读？ 例如，创建站点并将站点绑定到该站点，颁发SSL证书，配置备份等。也就是说，解决您的问题。

了解听众 。 我们将客户分为用户，管理员和开发人员。 但这还不足以创建有用的文本。 为了快速了解受众，您可以转到UX和产品，研究有关主题的支持请求及其答案，听一线电话，查看网站和博客（市场营销也会写必要的东西）。 而且只有在那之后才开始写作。

检查，编辑并再次检查 。 技术作者应进行初步检查。 在她之后。 然后值得将支持，市场和其他部门与审计联系起来。 然后，您需要查看样式和设计手册-编辑政策。 身边的人或其他技术作家让他做最后的校对。 如果您有编辑，那么他将担任这个阶段。

发布后分发文章 。 如果文档是书面的，则很可能有人需要它。 向公众展示并最大程度地使用它：翻译，参考产品，提供给市场，支持。 不要写到表中。

在码头上工作的50个问题

在处理文档时，我们重复了同样的错误。 他们花了太多时间检查文章，而起初看起来像灵丹妙药的指南却无济于事，因为问题出在方法和内容上。 为了使技术作者能够将文章快速地带到他们的脑海中，我们将所有我们经常问（或忘记问）的问题汇总在一起。 如果还要编写扩展坞，则使用。

目标

1.我为谁写文章？ 谁是未来的读者：用户，管理员，开发人员？
2.它要面对哪些任务（要完成的工作）？ 有此人的描述吗？
3.该用户的培训水平是多少？ 他已经知道了什么？ 对他来说不明显的是什么？
4.我该如何向新手用户解释这一点，同时又不激怒对基本事物的高级解释？
5.用户还需要向用户解释什么，以便他理解文章的主要内容？
6.本文适用于文档的哪一部分？
7.是否应在其他部分重复此条款或其中一部分？
8.我应该链接到哪些文章？
9.也许本文应该附有视频说明？

信息来源

10.当前用户是否对本文的主题有疑问？
11.现在的支持如何解释需要做什么？
12.市场营销部门是否撰写有关该主题的博客文章和新闻？ 他们可以“监视”他们的措辞，结构等吗？
13.网站上有关于此主题的任何部分吗？
14.该脚本包括UX和产品管理器吗？ 为什么这样做呢？
15.竞争对手如何描述这个问题？
16.在哪些方面您仍然可以看到最佳做法？

内容检查

17.您是否达到了本文的目标？
18.对于更高级的用户来说，一切都会清楚吗？
19.新手用户会清楚吗？
20.一切逻辑合乎逻辑吗？ 没有跳跃和深渊？
21.行动顺序是否正确？ 用户仅遵循此说明就能达到目标吗？
22.我们是否考虑了所有案例/用户路径？
23.文章是否适合所选部分？

布局检查

24.是否有无法阅读的文字？ 是否可以更换电路？
25.是否有较长的段落？
26.段落是否太短？
27.名单太长了吗？
28.列表是否过于复杂以至于无法感知（其中两个或三个以上级别）？
29.是否有足够的图像？
30.没有太多图像？ 我们在说明太明显的步骤吗？
31.如果有计划，它们是可以理解的吗？
32.桌子不难辨认吗？
33.页面整体看起来不错吗？

文学编辑

34.一切是否按照指南进行设计？
35.其余文档的样式是否一致？
36.有什么可以简化的建议吗？
37.是否有需要澄清的复杂术语？
38.是否有文书工作？
39.有重复吗？
40.没有什么会伤害您的听力吗？

最终校对

41.是否有错别字，拼写或标点错误？
42.连字符，段落和节是否正确？
43.所有图像都签名了吗？
44.接口元素的名称正确吗？
45.到处都有链接吗？ 他们工作并且去哪里？

出版后立即

46.文章是否包含“拉到”其他文章的部分？ 它们是否用宏修饰，以便将一篇文章中的更改自动应用于其他文章？
47.是否应从其他部分引用本文？ 如果是这样，哪个？
48.是否需要在产品中添加指向本文的快速链接？
49.我是否必须将链接发送给支持，市场或其他部门？
50.我必须提交一篇文章进行翻译吗？

此列表可以打印并放在桌面上或挂在墙上。 或变成检查清单。 一些问题可以带入业务流程。 例如，我们的问题已在YouTrack的常规开发过程中确定。 文档的任务经历了不同的阶段和部门，没有书面文档，您将无法发布功能。