优秀技术写手避免的6个错误
浏览：1
巴克励步
最近和几个做技术写作的朋友聊天，发现大家普遍被一个问题困扰：文档写出来没人看，或者看了也找不到要点。作为Baklib的研究员，我经常反思，到底什么样的在线帮助中心才能让用户真正用起来？其实，很多问题都出在写作习惯上。下面这6个误区，是我在和团队协作时反复踩过的坑——避开它们，你的帮助中心至少能提升一半效率。 不与领域专家沟通简单来说，不与领域专家（SMEs）沟通会导致软件文档包含错误或过时的技术信息
最近和几个做技术写作的朋友聊天，发现大家普遍被一个问题困扰：文档写出来没人看，或者看了也找不到要点。作为Baklib的研究员，我经常反思，到底什么样的在线帮助中心才能让用户真正用起来？其实，很多问题都出在写作习惯上。下面这6个误区，是我在和团队协作时反复踩过的坑——避开它们，你的帮助中心至少能提升一半效率。
不与领域专家沟通
简单来说，不与领域专家（SMEs）沟通会导致软件文档包含错误或过时的技术信息，或缺少重要的技术细节。这样的文档会引发大量用户不满，进而导致更多的用户支持邮件和电话，最终损害产品声誉。
为了避免这种情况，技术写手必须确保所有事实准确，并充分理解他们所写的软件产品，而SMEs可以在整个写作过程中提供必要的专业知识。换句话说，如果我们假设技术写作简化为以下五个阶段，那么SMEs的建议可能在任何阶段都需要。
如果你是一个正在规划新文档写作任务的技术写手，你应该向SMEs询问最佳的信息来源，以便熟悉你要写的软件产品、其功能和目标受众。由于规划阶段通常是你与SMEs首次沟通的时机，这也是建立良好工作关系的好机会，从而促进他们在后续写作中的参与。
💛🧡🧡客户评价：虽然报告功能已经变得更好，但我仍然希望看到一些改进。当然，这是一个“内容”管理平台，而不是“项目”管理平台，但我认为它可以更接近真正的项目管理体验。单个步骤和截止日期可以更易于使用。某种带有日历视图的总体内容规划将会非常棒。
此外，你应该确认是否有任何已有文档需要审阅，并在这个阶段解决你可能遇到的其他问题。这将确保写作过程的第二阶段——研究——朝着正确的方向进行，使你能够全面准确地理解你要写的主题。熟悉软件产品的过程取决于你对主题的初始了解程度，但通过与SMEs沟通可以加速这一过程。
正如Rachel Bishop所说：
为了加快进度，我阅读、谷歌搜索、研究——但我还联系了内部的SMEs，让他们带我了解我需要知道的内容。
一旦你写完了文档，审阅/编辑阶段应包含SMEs和其他利益相关者的反馈。总的来说，不在正确的时间与SMEs沟通——或者根本不沟通——来验证信息和请求澄清，会导致文档不准确和不完整。
假设受众了解多少
许多技术写手常犯的错误是假设而非确定目标受众了解多少。错误的假设会导致用户困惑、沮丧，误解文档，进而误用产品本身。这会导致软件采用率降低，损害消费者对产品和公司的信任，并使你的用户支持服务被无数消息和电话淹没。
因此，优秀的技术写手会确保他们了解目标受众，并根据受众的知识、技能和经验来定制写作。换句话说，你为特定领域的初学者（如初级开发者）编写的文档，将不同于为拥有更高级知识的用户（如高级开发者）编写的文档。
所以，在开始写作之前，你应该采访SMEs和其他相关人员，找出以下问题的答案：
这些问题——及其后续问题（如果答案不够精确）——将帮助你更好地了解目标受众、他们的平均技术知识水平和技能，以及他们的具体需求和关注点。这样，你就能创建用户友好的文档，满足这些需求，并预见常见错误或兼容性问题等潜在问题，可能还可以以故障排除指南的形式呈现。
换句话说，经验丰富的技术写手会深入挖掘SMEs和其他利益相关者，确定目标受众需要知道什么，并确保这些信息包含在文档中。总体而言，优秀的技术写手避免假设目标受众了解多少，而是投入时间和精力更好地了解他们的知识水平、具体需求和关注点，以创建受众友好的文档。
使用大量技术术语
虽然软件文档中不可避免会用到一些技术术语，但优秀的技术写手会避免使用大量技术行话和复杂语言，以免目标受众难以理解。这都要从了解目标受众开始，正如上一部分所述。
例如，如果你是为该领域的初学者（如初级开发者）写作，你需要比写给高级开发者的文档提供更详细的技术概念解释。同样，当为普通受众或其他领域的专家写作时，你不应该假设某个技术术语或首字母缩略词不需要解释，仅仅因为你（和你的专业社区）对其熟悉。
例如，在开发文档的上下文中，Kin Lane说：
这句话适用于所有其他类型的软件文档。无论他们为哪种软件写作，优秀的写手都应专注于使用通俗语言，尽可能避免技术行话。同时，优秀的写手也认识到软件开发中的技术语言是不可避免的，因此最好：
- 在文本中首次出现时简要定义技术术语和首字母缩略词
- 将它们组织成一个词汇表
自然，这将使用户受益，同时也使写手在专业术语的使用上更准确和一致。总之，技术写手应使用针对目标受众定制的通俗语言，并定义技术术语和首字母缩略词，以确保受众完全理解。
写太长的句子
除了避免过于复杂的技术语言，优秀的技术写手也尽量避免过长的句子。原因是这些句子会逐渐失去清晰度，使读者难以跟上。为了保持句子简短简洁，写手可以计算他们编写的软件文档的Gunning Fog Index。
Fog Index是Robert Gunning在1952年设计的一种可读性测试，用于评估合同等法律文件、学术论文和技术文档等书面材料的复杂性。以下是来自Readable的Fog Index计算公式：
该公式首先取文本样本中的单词数除以句数，得到平均句长；然后计算每100个单词中的复杂单词数，将其加到平均句长上，再将结果乘以0.4。得到的指数分数估计读者需要多少年正式教育才能一次阅读后理解文本。分数越低，用户越容易理解内容。
当然，这个来自20世纪50年代的实用可读性测试可以手动完成，但今天无需手动操作。有在线工具可以在几次点击中完成。一般来说，技术文档的分数不应超过17。不过，不同来源引用了不同的指数分数，因此理想的Fog Index最终取决于主题的复杂程度和目标受众的技术专长水平。
为了提高文档的可读性，技术写手还应努力分解长段落（例如使用项目符号），同时使用更短的单词和句子。总之，为确保写作清晰简洁，优秀的技术写手会尽可能保持句子简短。
仓促完成写作过程
尽管经常面临紧迫的截止日期、繁重的工作量和最后一刻的更改，优秀的技术写手会避免仓促完成写作过程。他们避免在截止日期临近时偷工减料，因为这会导致软件文档中的错误、不准确和不一致。这些缺陷会导致用户沮丧和软件采用问题。
因此，技术写手应遵循写作过程的阶段，通常包括研究、与SMEs沟通、创建大纲、写作、编辑和校对文档。让我们仔细看看为什么技术写手会感到迫不得已而仓促写作：
如上所述，工作量过大和不切实际的截止日期是主要原因，紧接着是终点线前未通知的更改。此外，与SMEs的困难可能包括回复问题或审阅文档滞后，或者无法清晰传达专业知识，甚至认为技术写手不值得他们花时间。技术写手Geoff Hart列出了他在与SMEs打交道时遇到的一些令人沮丧的问题：
SMEs在界面或底层算法中做未记录的更改，SMEs忘记同意让我及时了解这些更改，以及懒散或粗心的文档审阅。
自然，所有这些问题都会在写作的任何阶段拖慢写手的进度。因此，对技术写手来说，预先计划、尽早沟通、并留出缓冲时间至关重要。在Baklib平台上，我们可以利用模板和协作功能来简化流程，减少仓促带来的风险。
忽略文档的版本控制
最后但同样重要的是，优秀的技术写手会避免忽略文档的版本控制。当软件产品频繁更新时，文档必须同步更新，否则用户会参考过时的信息。版本控制确保文档与软件版本对应，历史记录可追溯。
在Baklib中，我们内置了版本管理功能，写手可以轻松追踪每次修改，并发布对应版本的文档。这避免了混乱和错误，确保用户始终看到正确的信息。
