回顾 8/3Sui AMA：与兰德尔和克莱一起进行技术写作
这个 AMA 与 Mysten Labs 的成员一起讨论技术写作。
Jen:
大家好。欢迎来到Sui AMA 系列的下一期，我们将与可爱的嘉宾 Clay 和 Randall 讨论技术写作的来龙去脉。请做一下自我介绍。
兰德尔：
你好，我叫兰德尔，我从事技术文档工作的时间比我愿意承认的要长，因为这会让你知道我有多老。我曾在学校学习过社会学、市场营销、研究和统计学，但我找不到这方面的工作，所以我自学了如何使用计算机。最后，我搬到了西雅图，开始在微软做承包商，然后转行做测试员。让我坚持技术写作的原因是，我发现自己非常喜欢帮助人们摆脱困境，解决他们的问题。我的使命是编写出优秀的文档，让人们在使用文档的过程中提高生活质量，让他们的老板高兴，并在职业上取得更大的成功。
克莱：
，我最初是一名记者。我是以理想主义者的身份进入这一行的，但我发现这一行其实非常压抑。之后不久，我进入了公共关系行业，然后又开始接触 HTML，这真的很有趣。我开始从事技术写作，非常喜欢把复杂的组件分解，然后解释如何完美地使用它们。这真的很有挑战性，同时也让我受益匪浅。通过帮助构建工具，我最终实现了讲述人们故事的愿望，让他们可以讲述自己的故事。
. . .
问题 1：社区成员如何参与 Mysten 项目？
Clay:
我喜欢这个！兰德尔和我强烈建议大家查看文档并帮助我们进行编辑。这很简单，你现在就可以做，我们还可以教你如何在 GitHub 网页编辑器中进行编辑。在这方面，我们还可以指出一些很酷的功能，这些功能可能会让网站看起来更有吸引力，更便于编辑和贡献。你应该知道，在 docs.sui.io的左上角，我们现在可以同时显示 Devnet 和最新版本。我们还在每个页面的底部列出了所有贡献者，包括内部和外部贡献者。我们还在底部提供了一个源代码链接，可以直接转到底层的 Markdown 文件。
我们直接在 GitHub 上与工程设计人员一起工作，因此您的贡献将直接进入Sui GitHub 项目。
. . .
问题 2：为什么工程团队更喜欢 Markdown 而不是 Notion 或 Google Docs 等工具？
克莱：
这是一个非常好的问题。因此，在理想状态下，我们都可以使用编辑器来生成我们想要的任何格式。工程师们通常已经在命令行下工作，他们可以使用命令行编辑器，比如 Vi 或 VS Code，Randall 和我现在正在使用 VS Code。它们更基于图形，而且编辑大量的 Markdown（本质上是一种转换为 HTML 的纯文本界面）也会容易得多。
兰德尔：
是的，我同意所有这些观点。我们更喜欢用 Markdoc，因为我们用 Markdoc 撰写。如果你在 GitHub repo 中编写 Readme，也会使用 Markdoc（我说 Markdoc 是因为我来自 Stripe，我们在那里有一个专有的 Markdown 实现，叫做 Markdoc）。但我想确保人们不会感到被迫或有义务在 Markdoc 中提交反馈。作为 Mysten 的技术撰稿人，我的目标之一是让那些想成为高级开发人员的人也能使用我们的文档。在我之前工作过的许多地方，我都发现了这个问题，因此我想做出改变。
因此，如果文档中有您不明白的地方，或者对您来说没有意义，我很乐意听取您的意见。对其他人来说，这可能也没有意义，也许我们可以重新措辞，或添加一些额外的上下文。
Jen:
我觉得这是一个很好的说明，因为就我而言，我只是来自非技术背景。也许我误解了作者希望人们如何理解这句话。团队中有技术撰稿人是一种恩赐，因为你能以更平易近人的方式组织大量信息。
. . .
问题 3：与编辑相比，您的工作中有多少是写作？
Randall:
人们总是对我们技术作家的工作有这样的误解。我花了大约 20% 的时间实际创作内容，10% 的时间进行编辑，60% 的时间获取信息并将其转化为内容。
Clay:
我们花了相当多的时间来整理工程人员提交的材料，还有一些时间用于编辑，这是因为我们成功地鼓励了大量内部和外部的变更审核请求（拉取请求）。
. . .
问题 4：如何扩大规模以满足数十名工程师和数千名用户的需求？
Randall:
有时是创造性地解决问题，有时是转移工作重点。
有时我们会开会并进行访谈，但很多时候我们只是在了解什么会对用户产生最大的影响和帮助。有时，我们做了足够好的文档，然后快速跟进，对其进行改进或迭代。我们能为用户提供的信息和帮助越多，就越容易将其转化为面向公众的内容。
Clay:
没错。兰德尔和我负责内部文档，就像我们负责外部文档一样。很多技术写作团队会把事情分得很细，要么选择内部文档，要么选择外部文档。但我们致力于两者兼顾，这也是我们扩大规模的方式。我们尽可能让人们更轻松地做正确的事情，这对他们自己、他们的职业生涯、他们的用户（最重要的是产品本身）都很重要。为此，我们提供流程、模板和指导，并直接帮助用户自己编写材料。无论需要什么。
. . .
问题 5：好医生的标准是什么？
Randall:
作为技术作家，这就像一个神奇的问题，我们总是问自己。当我刚开始写技术文章时，我认为我需要在我所有的内容上获得 80% 的好评率，但这其实是不可能实现的，因为你必须考虑到所有不同类型的人都在消费这些内容。
对我来说，质量的基本含义是，使用这个产品的人能否通过这个文档完成他们想要完成的任务？如果能，那么我认为这就达到了质量标准，但还有很多需要打磨的地方，比如：
- 主题是否易于发现？
- 我能在需要时找到所需的信息吗？
- 我为什么要做这件事？
- 现在你已经完成了这项任务，接下来我该怎么做？
因此，基本上可以说是提高了导航效率。你可以只用其中的一些东西来制作优秀的文档，但优秀的文档需要具备所有这些东西，还需要很多其他的修饰。
Clay:
很棒的回答。具体来说，对我来说，好的文档都有一些空白。我是达尔文信息类型架构的忠实粉丝： https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
它指出，技术信息可分为三类：
- 概念：如果您刚刚开始使用Sui ，那么您需要花时间从 docs.sui.io.
- 任务：这些是程序、方法和操作手册。请在我们的 "构建 "部分查找它们。你将在这里安装软件包、创建智能合约，然后构建、测试和发布它们。
- 参考资料：这些是表格、数据库和对象列表，您可以在其中选择自己的冒险。请在我们的 "探索 "和 "贡献 "部分查找它们。
当用户只想找到相关的命令或示例时，结构是防止他们混淆概念性材料的关键。我们根据关键用户旅程或 CUJ 来组织这些信息，预测受众需要做什么。我们关注的是用户而不是工具。
然后我们监控结果：分析、Discord 和内部意见。很快，我们就能发现我们的工作是有效的。然后我们寻找下一个要解决的问题，即网络统计中不会出现的差距。
仁：
嗯，你还指出了一些问题，我想有些听众希望更清楚一点，那就是你说的关键用户旅程是什么意思？
Clay:
这基本上是一张通往总体任务的用户旅程图。它可以帮助你实现目标，而不用花一整天时间去筛选基于工具的文档，来完成你的用户旅程。文档应该根据你需要完成的任务来使用，然后帮助你。你可能会接触一些工具来完成一个目标。这个过程应该是无缝的，除非绝对必要，否则不会让你深入了解每个工具的细节。
. . .
问题 6：除了编写文档，技术作家还做些什么？
Randall:
正如我所说的，我是网络管理员出身，所以我在网络领域能做的事情比做文档更多。我还做了很多安全测试工作。我还负责用户界面设计，我非常喜欢这个工作，因为这样我就可以按照自己的想法在屏幕上显示所有文字和文档链接。我们生成的内容就是你在网站上看到的内容，但我们的主要职责是在设计讨论或工程会议中充当用户代言人。
. . .
问题 7：如何确定受众？
Clay:
举个例子，我们真正关注的是应用程序游戏开发者，从 docs.sui.io其次是负责决策的执行层人员和技术负责人。因此，你会在 "构建 "选项卡中看到前者，而在 "学习 "选项卡中看到后者。不过，我们还是会首先介绍学习文档，因为每个人都应该了解其中的概念。
与此同时，我们现在有了完整的节点运行程序，很快就会有验证程序。我们知道，我们的受众会不断增加，我们必须与所有同行合作，为他们提供优质信息。这些会议非常适合呼吁找出差距，并与我们的同行合作，帮助我们定义每个受众，并真正尝试让公司和生态系统中的每个人都参与其中。
. . .
问题 8：作为社区，我们可以提供哪些最佳帮助？它们会得到认可吗？
Clay:
是的，这是一个很好的问题。我们正在考虑在我们的 "贡献 "版块创建一个页面，在这里大家可以突出自己与Sui 相关的作品。比如说，我知道你们很多人都是内容创作者，我们很乐意为你们建立一个主页，让你们能够突出自己的创造力。显然，我需要与内部人员合作来尝试这样做。
我们希望表彰你们，因此我们在 GitHub 上建立了自动档案，在每页底部列出贡献者。在这里，我们需要你们的帮助，主要是作为技术撰稿人，帮助我们修改现有的文本并形成新的部分。显然，这是我们的职责所在，也是我们需要做的。
其次，我们还希望强调你们正在做的所有很酷的事情。我在 Discord #content 频道看到了很多东西。也许，我们可以给你们提供一个渠道，在这里我们有一个社区贡献页面，你们可以直接进入，然后把一个表格放在一起，链接到你们的文本，并用一句话描述你们的创作，这样人们就可以从我们的网站上离开，我们也可以为你们吸引更多的眼球。
. . .
问题 9：技术写作的最大收获是什么？
Randall:
我是一名网络管理员，在一家管理式医疗公司工作。我有一位医生，他负责批准或拒绝报销申请。也许在某些情况下，每个人对他的评价都不太正面。他是那种''嘿，这很酷，去做吧''的人。当然，你想保住你的工作，所以你去努力完成它。我花了几个小时学习如何做他想让我做的事情，但很多时候他根本不会用。
在完成任务的过程中，我遇到的最大障碍是学习如何使用新技术、了解它的工作原理、知道我还需要做什么，以及所有的前提条件和其他东西。现在，作为一名技术作家，我所做的一切都是为了帮助人们更好地完成工作，这也是我每天坚持上班的原因。如果我的工作做得好，我就能影响数十亿人的生活。
珍：
棒极了。Clay 和 Randall 都希望提供最简单的方法来理解我们在 Mysten 世界和Sui 中推出的一些东西，他们的帮助和同理心让我怎么强调都不为过。
