技术写作：如何编写软件文档(Technical Writing: How to Write Software Documentation)

提供有关使用您的软件的相关信息的能力对于您的客户来说是否至关重要？您是否发现自己花了很多时间试图解释如何使用该软件？或者您是否从客户那里得到反馈，认为您的文档难以遵循、不一致甚至……令人困惑？

如果你回答“是！” 对任何这些问题并且愿意投入所需的时间和精力来完成这门实用课程，那么这门课程就适合您！

CNBC 在文章《公司现在正在寻找的 20 个最热门的工作技能》中引用了这门课程

在本课程结束时：

1. 您将能够执行所需的步骤并开始以技术作家的身份编写文档。
2. 您将能够向软件产品的用户解释准备、组织和交付软件文档的过程。
3. 您将能够使用 Canva 创建文档中所需的指导图像和图形。
4. 您将学习并练习如何按照讲师的Markdown写作模板在 GitHub wiki 中创建软件文档。
5. 您将了解如何在 Mural 中使用 2 卡排序技术进行用户研究。
6. 您将能够识别使文档成为高质量可交付成果的不同方面。

还：

• 您还将发现哪些是编写真正有帮助的软件文档的核心原则。
• 您将有机会尝试使用 GitHub wiki 编辑器进行写作。
• 您将了解图形的重要性以及可以使用哪些工具轻松创建教学图形。
• 最后，您将了解有关信息架构及其在软件文档中的重要性的更多信息。
• 最终，即使您以前从未担任过技术作家并且没有经验，您也将有机会创建自己的文档项目。

多年来，技术写作专业人员的核心活动不断发展。

我们从技术作家开始，只专注于技术写作。我们转变为信息开发人员，也考虑内容的图形方面和设计。今天，我们需要将写作技能、设计和图形、视频创作、多媒体、元数据和软件开发结合在一起，以满足用户的期望。

所有这些资产放在一起可以被描述为 用户帮助。

JPDocu 技术写作学院是一家培训公司，热衷于技术写作、软件文档、API 文档、信息架构和 DITA XML，并帮助我们的学生开始并快速推进他们的技术作家职业生涯。

我们的技术写作课程是欧洲多所大学技术通信大学课程的一部分，也是许多最好的软件开发公司新技术作家入职培训的一部分。

我们通过为下一代技术作家和信息开发人员提供简单易懂且实用的技术写作实践经验来塑造他们。

几年来，JPDocu 技术写作学院一直在为所有想要开始技术写作的人设计和提供培训。我们的学生很快就开始工作：

1. 技术作家（信息开发人员）
2. 信息架构师
3. 软件开发商

并在职业生涯中取得进步！

讲师 Jordan Stanchev 是一位用户辅助开发架构师，他亲自在课堂、在线课程、大学以及财富 100 强公司内部培训了数百人！

乔丹说：“我的目标一直是提供实用信息，以确保我的学生在课程结束后准备好提供真实的内容！

我为我的学生感到非常自豪，他们回到我这里并分享他们如何开始作为技术作家的第一份工作，或者他们如何利用他们在我的课程中学到的知识在职业生涯中取得进步！

这就是为什么我除了担任用户帮助开发架构师的日常工作之外，还开始投入时间教授技术写作技能。”

与其他课程不同，本课程以实践为导向。它将帮助您开发您作为软件开发公司的技术作家所需的作品集和工作样本。

你会学到什么？

本课程专为初级技术作家（通常是 IT 专业的学生）设计，涵盖以下主题：

• 技术写作到底是关于什么的？
• 技术写作的基础是什么？
• 您在 IT 技术写作领域会听到和使用哪些常见术语？
• 如何使用 GitHub wiki 编写技术文档？稍后，您将使用此材料来创建您的作品集，当您申请技术作家工作或晋升为高级开发人员时，您将希望将其添加到您的简历中。
• 从技术写作的角度来看，什么是信息架构？

在本课程结束时，您将了解如何开始编写用户指南、要考虑哪些最佳实践和规则，以及使用哪些工具进行编写。

除了：

• 您还可以找到录制的网络研讨会，让您感觉自己在大学课堂上与其他学生一起进行课程的实际练习。
• 您将有机会加入一个封闭的社区小组，在那里您可以与其他学生一起学习技术写作。
• 您将有机会与讲师一起参加现场网络研讨会，以获得指导并解答您可能遇到的问题。
• 各部分中的可下载材料可帮助您浏览内容并练习所学知识。

本课程不涵盖哪些内容？

作为一名初级技术作家，学习技术写作至少需要在大学学习两个学期并进行大量的写作练习。在 4-6 小时的课程中不可能提供所有可能的技术写作主题的深入信息。不过，您会了解基础知识！

• 这不是一门关于使用 MS Word 写作的课程！我们不会写书！我们不会编写非结构化文档！与其他技术写作课程告诉您的不同，MS Word 是编写技术文档的最差选择！它无法扩展，并且对于软件文档来说不够灵活！如果您认为技术写作就是写书，请选择其他课程！这门课程是为那些想在软件行业工作的人准备的，在软件行业，写一本书并称之为“软件文档”是不被认为是好的！
• 技术写作是一门需要写作的技能和学科。不要指望通过听几场讲座就能成为一名技术作家。您必须在本课程中进行写作和交流。这不是一个听的课程，而是一个听并做的课程！课程类型。
• 这不是英语课程。我们不会向您提供如何用英语写作的详细信息。
• 有很多工具可以用来写作。在本课程中，我们不会详细介绍可用于写作的工具，而是直接建议您仅使用其中的 1-2 个工具来入门。
• 本课程不涉及 API 文档。API文档是您仍然必须交付的一种软件文档，但目前本课程不讨论这一点。请参阅我们关于此主题的专门“如何编写 API 文档”课程。

您需要多长时间才能完成这门课程？

简短回答：

第 1 部分：技术写作入门 – 1 小时

第 2 部分：使用 Markdown 在 GitHub 中编写软件文档 – 2 个多小时

第 3 部分：软件文档中的图形 – 40 分钟

第 4 部分：信息架构基础知识 – 1 小时以上

第 5 部分：软件文档质量 40 分钟以上

奖励部分：额外的网络研讨会 – 3 小时以上

详细答案及解释：

第 1 部分：技术写作入门（作为对您的赞扬，因为您已经阅读了我们详细课程摘要的这一部分，这个 1 小时长的部分 是 免费的– 它本身就是一个迷你课程！即使您决定不学习购买整个课程 – 你一定要看看。）

我们首先快速、直接地概述端到端文档创建过程。

基本上，当您阅读介绍部分时，您应该基本了解软件文档中的技术写作的全部内容，以及使用技术写作技巧和技巧创建的主要资产（为客户提供的可交付成果）。这是软件文档、图像以及教学视频和多媒体。

完成这些内容并进行练习大约需要 1-2 小时。

第 2 部分：使用 Markdown 在 GitHub 中编写软件文档 – 2 个多小时

如何开始在 GitHub 上的 Wiki 中写作？本节介绍设置步骤以及 wiki 中使用的标记语言，并为您提供有关Markdown语言使用的提示（这在 wiki 中并不为人所知或没有记录！），例如：

– 如何创建表格

– 如何在 Wiki 上创建图像

– 如何为较长的页面创建目录 (TOC)

– 如何轻松链接 YouTube 视频

本节涉及一个非常重要的主题 – 如何为 GitHub 项目提供文档。Jordan 谈到了一种可能的选择，我们敢说 – 最简单的一种，在 GitHub 中提供文档。

完成这些内容并进行练习大约需要 2-4 小时。

第 3 部分：软件文档中的图形 – 40 分钟

图形创作技能对于技术作家来说有多重要？我想说，很多！本节讨论软件文档中创建图形的规则。此外，我还介绍了一些工具，这些工具可以让您轻松创建图形，而无需成为图形设计师。然后我们将使用 Canva 进行实践练习，以准备在您的文档中使用的信息图表。

完成这些内容并进行练习大约需要 1-2 小时。

第 4 部分：信息架构基础知识 – 1 小时以上

然后是下一部分 – 关于技术作家的信息架构和用户研究。它为您打开了大门，让您了解信息架构师（将其视为经验丰富的技术作家）开始完成其工作所需的基本知识。本部分为您提供有关如何使用虚拟白板（例如 Mural）与最终用户准备和执行卡片分类研讨会的分步说明。

浏览此内容大约需要 1 小时。

第 5 部分：软件文档质量 40 分钟以上

2021 年，我们启动了研究，以定义文档中的质量会议。许多参与者加入并分享了他们的反馈。分析和汇总结果后，研究结果即可与 JPDocu 技术写作学院的学生分享！

研究回顾在此奖金部分分享，为您提供以下问题的答案：

• 当我们谈论文档时，什么是质量？
• 高质量的文档有哪些特点？
• 您在文档中必须努力实现的每个质量方面的具体含义是什么？
• 如何开发实用的方法来衡量文档质量并将其与其他文档交付成果进行比较？

这不仅可以帮助您创建一些文档，还可以帮助您构建让您的客户满意的高质量文档！

奖励部分：额外的网络研讨会 – 3 小时以上

真正有趣的部分开始了。您会找到我与 JPDocu 技术写作学院的学生一起进行的现场研讨会的几段录音。您可以收听这些录制的课程并参与其中，就好像您真的与我和班上其他人一起在教室里一样。我认为这可能是一次非常酷的体验。最重要的是，我们深入探讨了前面几节中仅简要提及的主题。

每个录制的课程需要 60-90 分钟，包括每个课程中的练习。作为课程的一部分，我邀请我的学生参加此类实时网络研讨会，您可以在我们的 Facebook 封闭群组中看到这些研讨会。

以下是学生对本课程的评价：

Karina Delcheva，技术作家

“我发现乔丹的课程结构完美（正如您对该领域专家的期望），可以帮助您掌握技术写作的概念。它帮助我通过易于遵循的说明和示例进行练习，快速培养实用技能.这门课程的Facebook页面为我提供了一个支持社区和讲师举办的额外网络研讨会，这对于获得技术作家所需的更多样化的技能来说是一笔巨大的财富。现在我已经准备好申请我的第一份技术写作工作了。 ”

Grace Tan，技术作家

“在我追求成为技术沟通者角色的过程中，Jordan 的初学者课程《技术写作：如何编写软件文档》为我指明了正确的方向。该课程结构良好，讲师也展示了该领域的专业知识。很高兴能够接触技术写作的标准和最佳实践以及当今使用的常用工具。我也很高兴参与实践活动并熟悉不同的工具。 ”