技术写作原理01 - 了解读者｜ 豆包MarsCode AI 刷题

苏Synic22
148 阅读6分钟

文档写作

文档的主要作用：

  1. 知识传递：文档作为信息和知识的载体，可以帮助个人或团队之间分享和传递专业知识，也可以帮助新成员快速了解项目背景和工作流程。

  2. 参考和检索：良好的文档可以作为参考资源，当需要查找特定信息时，可以快速检索和定位。

  3. 用户指南和支持：对于产品用户来说，文档提供了如何使用产品的信息和技术支持。

  4. 技术规范：详细说明了系统架构、接口定义和编程接口。

  5. 沟通工具：文档是沟通的工具，可以帮助团队成员理解项目目标和任务要求。

  6. 协作和协调：在团队工作中，文档有助于协调不同成员的工作，确保信息同步和一致性。

  7. 质量控制：文档可以帮助检查和维护产品质量，通过文档化的测试案例和质量标准来确保产品符合预期。

  8. 项目管理：文档在项目管理中用于规划、跟踪进度和监控项目状态。

为什么要了解读者？

  1. 保证文档可用性
  2. 完成任务

什么是了解读者？

  1. 明确读者身份：小白用户 or 资深用户？运维人员 or 开发人员？
  2. 明确读者阅读目的：了解一个概念、完成一个步骤，还是查阅一个参数解释？
  3. 明确读者所需信息：根据读者的认知能力提供所需信息。

文档最强调功能性，如果是设计思路的文档，那就要分块介绍设计方案、解决思路和具体实现，保证在读者阅读完之后可以快速对此种设计方案形成一个详细的框架。如果是用户手册，则重点应该放在使用上面，此时就要详细介绍各项功能，让读者遇到问题的时候可以通过查阅手册快速解决。

案例

修改前

  • 文件菜单按钮:用于创建新文件，打开文件重命名文件等
  • 裁剪按钮:用于裁剪出图片中选中的区域
  • ……

修改后

  • 如何捕捉图片
  • 如何选择背景
  • 如何绘制矩形
  • 如何绘制椭圆形和圆形

这是一个绘图软件的用户手册，在修改前的版本里作者很详细的描述了，界面上的各个控件的功能，该文档与其说是用户手册，不如说是功能清单。 而修改后的文档则是基于读者的视角，来介绍这个软件可以解决的具体问题。 修改后的版本读者可以快速定位到有用的内容，那文档的可用性就大大提高了。

信息差

文档要尽可能的弥补读者和作者之间的信息差，说白了就是考虑的要周到，提供差异性的内容。

常见的信息差来源

1.术语（黑话）

Bad case

  • 911
  • p3
  • 虾哥

Good case

允许您创建消息组以适应不同的业务场景。在不同的国家或地区，使用的签名和可用的模板。

签名 - 指在文本消息正文之前的xxx，用于识别公司或业务。

  1. 使用标准术语
  2. 要统一使用术语的表示方法，不要换来换去，例如：API - 接口 - 调用方法
  3. 提供术语的解释，可以在术语出现的地方加一个链接，或者解释

2.相似物

一个产品提供了两个相似的功能，文档需要帮助读者辨析，方便做出选择

案例

为满足您对原生环境的开播与观播需求，企业直播将相关底层能力整合包装，输出了一套支持在您自身产品独立接入的 aPaas 方案已即 Android SDK、i0S SDK 和 Web SDK。SaaS 方案和 aPaaS 方案的企业直播观播页面存在一定的功能差异，具体支持情况见下表。

说明 iframe 嵌入能力与 SaaS 方案相同。详情请参见 iframe 嵌入口。

功能说明SaaS方案（PC端+移动端）Android SDK & iOS SDKWeb SDK
自定义观看域名使用专属域名观看直播支持不适用支持
社交平台分享观众可以将直播分享至微信、飞书等各大社交平台。支持二维码分享和复制观看地址。支持支持支持

这里展示的是一个直播产品中，两个接入方式的功能对比，如果没有这个表，用户就可能会遇到开发到一半却发现当前方式并不支持某种功能，而需要全部替换成另一个方法。 这也就是说在遇到岔路口的时候，要清晰的给出各种选择的详细信息和对比。

3.新事物

所有新出现的事物都需要充分解释其来源。 下例文档详细交代了如何获取 AppID、AppName和 region。这些信息一旦缺失，就可能影响客户满意度、并带来额外的客户支持成本。

@Override
public string getAppID() {
    return mAppId;// 申请 TTSDK License 时使用的 AppId，请联系技术支持获取
}
@0verride
public String getAppName() {
    return mAppName;// 申请 TTSDK License 时使用的 AppName，请联系技术支持获取,
}
@Override
public String getAppRegion() {
    return mRegion;//申请TTSDK License 时使用的 region，即 china.
}

这里展示的是一份SDK的集成文档，在解释这几个字段时，文档都会特别的去说明可以通过何种途径获取信息

如何了解读者？

主动走近读者

  1. 邀请同事评审
    • 把身边的同学作为目标受众，获得反馈意见
  2. 读者访谈
    • 与读者约一次访谈，了解他们对文档的期待、建议和意见。
  3. 文档支持群
    • 建立文档支持群，收集第一手的文档问题。这是一个长期、可靠、优质的渠道，通过该途径可以收集到许多鲜活的、高价值的文档反馈。

时常问自己

  1. 读者从哪里来 ?
    • 背景是什么？读者遇到了什么困难，要完成什么任务？读者最开始是什么状态？他们此时在做什么，手边有哪些资源？
  2. 读者在哪儿 ?
    • 读者此时所处状态？比如，此时在哪个文件夹下?读者怎么确认他们处于文档里说的这个状态？比如执行某个命令，应该返回什么结果？
  3. 读者到哪里去 ?
    • 为什么要告诉读者这些信息?对他们有什么用？下一步要做什么？

总结

  1. 为什么要了解读者？
    • 为了写出可用性强的文档
  2. 什么是了解读者？
    • 明确读者身份
    • 明确读者阅读目的
    • 明确读者所需信息——常见的信息差：术语、相似物、新事物
  3. 如何了解读者
    • 主动走进读者
      • 邀请同时评审
      • 读者访谈
      • 文档支持群
    • 头脑风暴
      • 读者为什么来看文档？
      • 读者如何快速确认自己的状态？
      • 读者下一步应该做什么？
avatar
文章
阅读
粉丝