Microsoft Learn 样式和语音快速入门

  • 项目

此快速入门是针对 Microsoft Learn 上的出版物的书面技术内容的简短指南。 无论是创建新文档还是更新现有文档，这些指南均适用。

最佳做法：

  • 检查文章中的拼写和语法，即使需要复制粘贴到 Microsoft Word 中来执行此操作。
  • 采用随意且友好的语调，就像是在和其他人面对面聊天一样。
  • 使用结构简单的句子。 易于阅读的句子意味着读者可以快速使用你共享的指南。

使用 Microsoft 语调原则

我们努力做到在撰写 Microsoft Learn 技术内容时遵循这些原则。 可能无法始终达到要求，但仍要不断努力！

  • 关注意图：客户在查阅我们的文档时，都有自己的专门用途。 开始撰写之前，需要清楚客户是谁，他/她尝试完成的任务是什么。 然后，撰写文章以帮助特定客户完成特定任务。
  • 使用常用字词：尝试使用自然语言，客户使用的字词。 可以不正式，但不能缺少技术性。 提供介绍新概念的示例。
  • 内容简明扼要：别写废话。 使用肯定语气，不要使用多余词汇或者大量限定词。 句子简短明了。 突出文章重点。 如果某个任务需要限定词，请将其置于句首或者段落开头。 此外，尽量少用备注。 如果可以，尽量使用屏幕截图代替文字。
  • 使文章通俗易读：将最重要的内容放在开头。 分段落描述，将冗长的流程细分为更易于管理的多组步骤。 （包含 12 个以上步骤的流程可能过长。）请使用屏幕截图来增加清晰程度。
  • 表示感同身受：在文章中采用共鸣式语调，尽量避免出现否认内容。 真诚地表达客户会感到困扰的地方。 确保文章关注客户真正关心的内容，而不是成为一个单纯的技术讲座。

考虑本地化和机器翻译

我们的技术文章会被翻译为多种语言，某些内容会针对特定的市场或地区进行修改。 用户还可能会在网络上使用机器翻译来阅读这些技术文章。 因此，撰写时切记以下几点：

  • 确保文章没有语法、拼写或是标点错误：通常都应该做到这一点。 某些 Markdown 编辑器（如 MarkdownPad 2.0）带有基本的拼写检查程序，但是最好将文章中（HTML 形式显示）的内容粘贴到 Word 中进行检查，因为 Word 具有更强大的拼写和语法检查程序。
  • 尽量确保句子简洁明了：复合句或者大量从句会使翻译难度增加。 尽量将句子拆分为短句，不要出现过于冗长或者看起来很奇怪的句子。 我们希望使用自然语言撰写文章。
  • 采用简单且一致的句子结构：一致的结构更易于翻译。 避免插入语和边注，尽量直接切入正题。 签出几篇已发布的文章。 如果某篇文章采用友好、便于阅读的风格，请用作范本。
  • 措辞和大小写一致：再次强调，一致性很关键。 如果不是在句首或者不属于专有名词，切勿使用大写形式。
  • 包含“小词”：在英语中，“小词”即我们认为较小且不重要的那些单词（例如“a”、“the”、“that”和“is”），由于它们在上下文中易于理解，这对于机器翻译而言至关重要。 请务必加入这些单词。

需要注意的其他风格和语调问题

  • 不要断开带注释或边注的步骤。
  • 对于包含代码片段的步骤，将关于步骤的其他信息作为注释放入代码中。 这会减少用户需要仔细阅读的内容量。 关键信息被复制到代码项目中，可以提醒用户他们稍后引用的代码的具体意义。
  • 对所有标题使用句首大写。
  • 使用“sign-in”（登录）而不使用“log-in”。
  • 有关详细指导，请参阅 Microsoft 写作风格指南。

本地化文档

  • 如果要参与本地化文档的编写，请参阅全球化参考。
  • 若要获取本地化指南，技术出版物中的语言风格及用法相关的信息，以及市场特定数据格式的相关信息，请下载你所在国家/地区语言版本的风格指南。
  • 请访问 Microsoft 术语搜索你所在国家/地区语言版本的产品特定批准术语或者下载你所在国家/地区语言版本的 Microsoft 术语集。
  • 要了解有关本地化的详细信息，请参阅 Microsoft 写作风格指南中的“全局通信”。

注意

大多数本地化文档不提供通过 GitHub 编辑或提供反馈的功能。 若要提供有关本地化内容的反馈，请使用 https://aka.ms/provide-feedback 表单。