软件文档只是一组文章。 但即使是它们也会让你发疯。 首先，您花费很长时间寻找必要的说明。 然后你就能理解晦涩难懂的文字了。 你按照写的做了，但问题没有解决。 你寻找另一篇文章，你变得紧张......一个小时后，你放弃一切并离开。 这就是糟糕的文档的运作方式。 是什么造成了这种情况以及如何修复它 - 请阅读切口下方的内容。
我们的旧文档有很多缺点。 我们已经对其进行了近一年的重新设计，以便上述情况不会影响我们的客户。 看， и .
问题一：文章表述不清、写得不好
如果文档无法理解，那么它还有什么意义呢？ 但没有人会故意写一些难以理解的文章。 当作者不考虑读者和目的、泼水并且不检查文本错误时，就会发生这种情况。
- 听众。 在写文章之前，您需要考虑读者的准备程度。 合乎逻辑的是，在一篇针对初学者的文章中，您不应该跳过基本步骤并留下不加解释的技术术语，但在一篇有关只有专业人士才需要的罕见功能的文章中，您应该解释 PHP 一词的含义。
- 目标。 还有一件事需要提前考虑。 作者必须设定明确的目标，确定文章的有用效果，并决定读者读完后要做什么。 如果不这样做，您最终将只是为了描述而描述。
- 水和虫子。 有很多不必要的信息和官僚主义、错误和拼写错误干扰感知。 即使读者不是语法纳粹分子，文本中的粗心也会让他感到厌烦。
考虑一下上面的提示，文章将会变得更加清晰 - 保证。 为了让它变得更好，请使用我们的 .
问题 2. 文章并不能回答所有问题
如果文档跟不上开发的步伐，不能回答真正的问题，并且其中的错误多年都没有得到纠正，那就很糟糕了。 这些问题与其说是作者的问题，不如说是公司内部流程组织的问题。
文档跟不上发展
该功能已经发布，营销计划涵盖它，但结果发现新文章或翻译仍然不在文档中。 我们甚至因此不得不推迟发布。 你可以要求大家按时把任务交给技术作家，但这是行不通的。 如果该过程没有自动化，情况就会重演。
我们对 YouTrack 进行了更改。 在功能开始测试的同时，撰写有关新功能的文章的任务就落到了技术作家身上。 然后营销人员了解这一点，以便为促销做好准备。 通知也会发送到 Mattermost 企业通讯软件，因此您不可能错过来自开发人员的新闻。
文档不反映用户请求
我们习惯这样工作：一个功能出来了，我们就讨论它。 我们描述了如何打开、关闭它以及进行微调。 但是，如果客户以我们意想不到的方式使用我们的软件怎么办？ 还是其中存在我们没有想到的错误？
为了确保文档尽可能完整，我们建议分析支持请求、专题论坛上的问题以及搜索引擎中的查询。 最热门的主题将转移给技术作家，以便他们补充现有文章或撰写新文章。
文档没有得到改进
马上就做到完美是很困难的，总会有错误的。 您可以希望得到客户的反馈，但他们不太可能报告每一个拼写错误、不准确、难以理解或未找到的文章。 除了客户之外，员工也会阅读文档，这意味着他们会看到相同的错误。 这个可以用！ 您只需要创造方便报告问题的条件即可。
我们在内部门户上有一个小组，员工可以在其中留下有关文档的意见、建议和想法。 支持是否需要一篇文章，但它不存在？ 测试人员是否注意到了不准确性？ 合作伙伴是否向开发经理抱怨过错误？ 都在这个组里！ 技术作家立即修复一些问题，将一些问题转移到 YouTrack，并给其他人一些时间思考。 为了不让话题平息，我们时不时提醒大家小组的存在以及反馈的重要性。
问题3. 需要很长时间才能找到合适的文章。
找不到的文章并不比找不到的文章好。 好的文档的座右铭应该是“易于搜索，易于查找”。 如何实现这一目标？
整理结构，确定选题原则。 结构应该尽可能透明，这样读者就不会想“我在哪里可以找到这篇文章？” 总而言之，有两种方法：从界面和从任务。
- 从界面上看。 内容与面板部分重复。 旧的 ISP 系统文档中就是这种情况。
- 来自任务。 文章和章节的标题反映了用户的任务； 标题几乎总是包含动词和“如何做”问题的答案。 现在我们正在转向这种格式。
无论您选择哪种方法，请确保主题与用户正在寻找的内容相关，并且以专门解决用户问题的方式进行涵盖。
设置集中搜索。 在理想的情况下，即使您拼写错误或语言错误，搜索也应该有效。 到目前为止，我们在 Confluence 中的搜索还不能满足我们的要求。 如果您有很多产品并且文档很通用，请根据用户所在的页面定制搜索。 在我们的例子中，主页上的搜索适用于所有产品，如果您已经进入特定部分，则仅适用于其中的文章。
添加内容和面包屑。 当每个页面都有菜单和面包屑时，这是很好的——用户当前页面的路径，并且能够返回到任何级别。 在旧的 ISPsystem 文档中，您必须退出文章才能看到内容。 不方便，所以我们把它固定在新的上。
在产品中放置链接。 如果人们一次又一次地提出同一问题的支持，那么在界面上添加一个提示及其解决方案是有意义的。 如果您有数据或了解用户何时遇到问题，您还可以通过邮件列表通知他们。 向他们表示关心并减轻支持负担。
弹出窗口的右侧是有关在 ISPmanager 的域管理部分中设置 DNSSEC 的文章的链接
在文档中设置交叉引用。 相互相关的文章应该有“链接”。 如果文章是连续的，请务必在每个文本的末尾添加前进和后退箭头。
最有可能的是，一个人首先不会向你寻找问题的答案，而是向搜索引擎寻找答案。 如果由于技术原因没有指向文档的链接，那将是一种耻辱。 所以要注意搜索引擎优化。
问题4.过时的布局干扰感知
除了糟糕的文本之外，文档也可能因设计而被破坏。 人们习惯于阅读写得好的材料。 博客、社交网络、媒体——所有内容的呈现不仅美观，而且易于阅读、赏心悦目。 因此，你很容易理解一个人看到下面截图中的文字时的痛苦。
本文中有太多截图和亮点，没有帮助，只会干扰感知（图片可点击）
您不应该长时间阅读带有一堆效果的文档，但您需要考虑基本规则。
布局。 确定正文宽度、字体、大小、标题和填充。 聘请设计师并接受工作或自己做，请阅读 Artyom Gorbunov 的书“版式和布局”。 它只提供了布局的一种视图，但已经足够了。
分配。 确定文本中需要强调的内容。 通常，这是界面、按钮、代码插入、配置文件、“请注意”块中的路径。 确定这些要素的分配并将其记录在法规中。 请记住，分泌物越少越好。 当它们很多时，文本就会很吵。 即使是引号，如果使用得太频繁也会产生噪音。
屏幕截图。 与团队就在什么情况下需要屏幕截图达成一致。 绝对没有必要每一步都进行说明。 大量屏幕截图，包括。 单独的按钮，干扰感知，破坏布局。 确定屏幕截图的大小以及突出显示和签名的格式，并将其记录在规定中。 请记住，插图应始终与所写内容相对应且相关。 同样，如果产品定期更新，就很难跟踪每个人。
文字长度。 避免文章过长。 将它们分成几个部分，如果不可能，请将带有锚链接的内容添加到文章的开头。 使文章在视觉上更短的一个简单方法是将一小部分读者所需的技术细节隐藏在剧透下。
格式。 在您的文章中结合多种格式：文本、视频和图像。 这将改善感知。
不要试图用漂亮的布局来掩盖问题。 老实说，我们自己希望“包装器”能够保存过时的文档 - 但没有成功。 这些文本包含太多视觉噪音和不必要的细节，以至于法规和新设计无能为力。
上述大部分内容将取决于您用于文档编写的平台。 例如，我们有 Confluence。 我也不得不和他一起修补。 如果有兴趣，请阅读我们的网络开发人员的故事： .
从哪里开始改进以及如何生存
如果您的文档与 ISPsystem 的文档一样庞大，并且您不知道从哪里开始，请从最大的问题开始。 客户不理解该文件 - 改进文本、制定法规、培训作者。 文档已过时 - 请注意内部流程。 从有关最受欢迎产品的最受欢迎文章开始：寻求支持、查看网站分析和搜索引擎中的查询。
让我们马上说——这并不容易。 而且它也不太可能很快发挥作用。 除非你刚刚开始并立即做正确的事情。 我们确信的一件事是，随着时间的推移，情况会变得更好。 但这个过程永远不会结束:-)。
来源： habr.com