软件文档只是文章的集合，但是即使它们也会使您发疯。 首先，您需要长时间寻找正确的说明，然后您才能理解晦涩难懂的文字，照原样编写，但问题仍未解决。 您正在寻找另一篇文章，您很紧张……一个小时后，您随地吐痰然后离开。 这就是不良文档的工作方式。 是什么原因以及如何修复-请仔细阅读。
我们的旧文档有很多缺陷。 近一年以来，我们一直在进行处理，因此上述情况与我们的客户无关。 看看它是 怎么变成了 。
问题1：难以理解的，写得不好的文章
如果找不到文档，那有什么意义？ 但是没有人故意写晦涩的文章。 当作者不考虑受众和目的，倒水并且不检查文本是否有错误时，便会获得它们。
- 听众 。 在撰写文章之前，您需要考虑读者的准备水平。 顺理成章的是，在为初学者准备的文章中，您不应跳过基本步骤，而不必对技术术语进行解密，而在有关仅对专业人士必需的稀有功能的文章中，请仔细阅读PHP这个词的含义。
- 目的 。 您应该事先考虑的另一件事。 作者应设定明确的目标，确定文章的有用效果，并决定读者在阅读文章后会做什么。 如果不这样做，则为了描述而获得描述。
- 水和虫子 。 许多不必要的信息和文书，错误和错别字会干扰感知。 即使读者不是文法国家，文本中的疏忽也会将他推开。
考虑上面的技巧，文章将变得更加清晰-保证。 为了使它更好，
在处理技术文档时 ，请
回答我们的
50个问题 。
问题2。文章不能回答所有问题
如果文档无法跟上开发进度，无法回答真实的问题以及多年未解决的错误，那就很糟糕。 这些问题与其说是公司内部流程的组织，不如说是作者。
文档跟不上发展
该功能已经在发行版中，营销计划已对其进行了覆盖，事实证明，新文章或翻译仍未包含在文档中。 因此，我们甚至不得不推迟发布。 您可以要求每个人都按时将任务交给技术作家，但这是行不通的。 如果该过程不是自动化的，则将重复这种情况。
我们对YouTrack进行了更改。 撰写有关新功能的文章的任务落在技术作家开始测试机会之时。 然后，营销人员了解了她，以准备晋升。 通知也出现在企业通讯工具Mattermost中，因此，根本不可能错过开发人员的消息。
该文档未反映用户要求
我们以前是这样工作的：一项功能问世了，我们对此进行了讨论。 我们介绍了如何打开，关闭和进行精细设置。 但是，如果客户以我们意想不到的方式使用我们的软件怎么办？ 还是他犯了我们没有想到的错误？
为了使文档尽可能完整，我们建议您分析支持请求，主题论坛上的问题以及搜索引擎中的查询。 最受欢迎的主题应该传递给技术作家，以补充现有文章或撰写新文章。
文档没有得到改进
马上就很难做到完美，反正会有错误。 您可以依靠客户的反馈，但他们不太可能报告每一个错别字，不准确，难以理解或未知的文章。 除客户外，员工还阅读文档，这意味着他们看到相同的错误。 可以使用！ 只需要创建容易报告问题的条件。
我们在内部门户网站上有一个小组，员工可以在其中留下有关文档的评论，建议和想法。 支持需要一篇文章，不是吗？ 测试人员是否注意到错误？ 合作伙伴向开发经理抱怨错误？ 这个组中的一切！ 技术撰稿人立即修复某些问题，将其转移到YouTrack，进行思考。 为了保持话题安静，我们不时回顾该小组的存在以及反馈的重要性。
问题3：找到合适的文章需要很长时间
找不到的文章比没有的文章更好。 好的文档的座右铭应该是“易于搜索，易于查找”。 如何实现呢？
简化结构并确定选择主题的原则 。 该结构应尽可能透明，以使读者不要认为“我在哪里可以找到本文？” 总而言之，有两种方法：从界面和从任务。
- 从界面。 内容重复面板的各个部分。 原来是ISPsystem文档中的内容。
- 从任务。 文章标题和章节标题反映了用户的任务； 标题几乎总是包含动词和“如何做”问题的答案。 现在我们转向这种格式。
无论选择哪种方法，都要确保该主题满足用户的需求并被覆盖，以便用户准确地解决他的问题。
建立集中搜索 。 在理想的世界中，即使您对语言感到难过或错误，搜索也应该可以进行。 我们在Confluence的搜索尚无法满足要求。 如果您有很多产品，并且文档是常规的，则使搜索适应用户所在的页面。 在我们的案例中，主要搜索适用于所有产品，如果您已经在特定部分中，则仅搜索其中的文章。
添加内容和面包屑 。 最好在每个页面上都有一个菜单和面包屑-用户到当前页面的路径，并可以返回任何级别。 在旧的ISPsystem文档中，您必须退出本文才能进入内容。 这很不方便，因此在新版本中我们对其进行了修复。
安排产品中的链接 。 如果人们不时提出相同的问题支持，则可以在界面的解决方案中添加提示。 如果您有数据或了解用户在什么时候遇到问题，也可以通过时事通讯通知他。 小心并从支撑物上卸下负载。
弹出窗口的右侧是ISPmanager域管理部分中有关DNSSEC设置的文章的链接。在文档中设置交叉引用 。 相关文章应“链接”。 如果文章是连续的，请确保在每个文本的末尾添加前进和后退箭头。
一个人最有可能首先去寻找问题的答案，而不是您的问题，而是搜索引擎的问题。 如果由于技术原因在那里没有指向文档的链接，那真是遗憾。 因此，请注意搜索引擎的优化。
问题4：过时的布局会干扰感知
除了不好的文字外，该设计还会破坏文档。 人们习惯于阅读制作精良的材料。 博客，社交网络，媒体-所有内容不仅呈现精美，而且易于阅读，令人愉悦。 因此，您可以轻松地理解看到文本的人的痛苦，如下面的屏幕截图所示。
本文中的屏幕截图和选择太多，以至于它们无济于事，而只会干扰感知（图片可点击）在文档中花很多篇幅进行冗长的练习是不值得的，但是您需要考虑基本规则。
布局 。 定义主要文本的宽度，字体，大小，标题和缩进。 聘请设计师并接受工作或自己完成工作，请阅读Artyom Gorbunov的著作《版式和布局》。 它仅显示布局中的一种视图，但已足够。
分配 。 在文本中定义需要强调的内容。 通常，这是界面，按钮，代码插入，配置文件，“注意”块中的路径。 设置这些元素的选择内容，并在计划中解决。 请记住，排泄越少越好。 当它们很多时，文字“发出噪音”。 如果经常使用引号，也会产生噪音。
屏幕截图 在需要截屏的情况下，与团队安排。 绝对没有必要说明每个步骤。 大量的屏幕截图，包括 单个按钮会干扰感知，破坏布局。 确定屏幕截图中所选内容和标题的大小以及格式，并按规定进行修复。 请记住，插图必须始终是书面的和相关的。 同样，如果定期更新产品，则很难跟踪每个产品。
文字的长度 。 避免过长的文章。 将它们分成几部分，如果不可能，请将锚定链接的内容添加到文章顶部。 一种使文章视觉上更短的简单方法是将一小部分读者所需的技术细节隐藏在扰流板下。
格式 在文章中组合几种格式：文本，视频和图像。 这将改善知觉。
不要试图用漂亮的布局掩盖问题。 老实说，我们自己希望“包装器”可以保存过时的文档-不能解决。 这些文本有太多的视觉噪音和不必要的细节，以至于法规和新设计无能为力。
以上大部分内容将由您用于文档制作的网站决定。 例如，对于我们来说，这就是Confluence。 他还不得不修补。 如果有兴趣，请阅读我们的Web开发人员的故事：
融合公共知识库：更改设计并设置语言分离 。
从哪里开始改进以及如何生存
如果您的文档和ISPsystem一样庞大，并且您不知道要抓什么，请从最严重的问题开始。 客户不了解如何改进文本，制定法规和培训作家。 文档已过时-承担内部流程。 从有关最受欢迎产品的最受欢迎文章开始：寻求支持，查看网站分析和搜索引擎查询。
让我们马上说-这并不容易。 而且很快也不太可能成功。 除非您只是立即开始并立即做。 我们肯定知道一件事-随着时间的推移它将变得更好。 但是这个过程永远不会结束:-)。