技术写作:如何编写软件文档

根据技术写作的 12 条主要原则,在 GitHub wiki 中学习编写软件文档的行之有效的策略!

课程英文名:Technical Writing How to Write Software Documentation

此视频教程共nan,中英双语字幕,画质清晰无水印,源码附件全

![](https://cdn.xueshu.fun/Technical Writing How to Write Software Documentation.jpg)

课程地址:https://xueshu.fun/1426

课程内容

你会学到什么

  • 了解开始编写应用软件文档所需的条件
  • 了解如何使用 Markdown 在 GitHub Wiki 中编写文档
  • 试用可帮助您立即开始编写帮助内容的工具和基础设施
  • 了解如何准备、构建和开发有助于用户使用您的软件的信息
  • 学习结构化写作的基础知识
  • 了解元数据和分类法对于提高用户辅助资产可查找性的重要性
  • 了解如何使用 Canva 为您的软件文档制作图形

要求

  • 您将需要一台 PC 或笔记本电脑,您可以在其中开发内容作业或安装我们将在培训过程中试用的特定软件

描述

提供有关使用您的软件的相关信息的能力对您的客户来说是必不可少的吗?您是否发现自己花费数小时试图解释如何使用该软件?或者您是否从客户那里得到反馈说您的文档难以遵循、不一致甚至……令人困惑? 

如果你回答“是!” 对于这些问题中的任何一个,并愿意投入所需的时间精力来完成这门实用课程,那么这门课程就是为你准备的! 

CNBC 在文章“公司目前正在寻找的 20 个最热门的工作技能”中引用了这门课程

在本课程结束时:

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

还:

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

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

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

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

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

  1. 技术作家(信息开发人员)
  2. 信息架构师
  3. 软件开发人员

并在他们的职业生涯中取得成功!

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

Jordan 说:“我的目标一直是传递实用信息,以确保我的学生在课程结束后立即准备好传递真实内容!

我为我的学生感到骄傲,他们回到我身边分享他们如何开始他们作为技术作家的第一份工作,或者他们如何利用他们在我的课程中学到的知识在他们的职业生涯中取得进步!

这就是为什么我除了作为用户辅助开发架构师的常规工作之外,还开始投入时间教授技术写作技巧。”

与其他课程不同,本课程以实践为导向。它将帮助您开发您的投资组合和您需要申请作为软件开发公司的技术作家的工作样本。

你会学到什么?

本课程专为初级技术作家(通常是 IT 学生)设计,涵盖以下主题:

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

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

除了:

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

本课程未涵盖哪些内容?

作为初级技术作家学习技术写作需要至少 2 个学期的大学学习和大量的写作练习。在 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,技术作家

“我发现 Jordan 的课程结构完美(正如您对该领域的专家所期望的那样),可以帮助您掌握技术写作的概念。它通过带有易于理解的说明和示例的练习帮助我快速发展实用技能. 这门课程的 Facebook 页面为我提供了一个支持社区和讲师举办的额外网络研讨会,这是获得技术作家所需的更多不同技能的重要资产。现在我准备申请我的第一份技术写作工作。 “

Grace Tan,技术作家

在我追求成为技术沟通者角色的过程中,Jordan 的初学者课程技术写作:如何编写软件文档让我走上了正确的方向。课程结构合理,讲师展示了该领域的专业知识。它是很高兴能够接触到技术写作的标准和最佳实践以及当今使用的常用工具。我在动手实践活动中也很开心,并让自己熟悉了不同的工具。 ”

所以,现在就注册,看看为您的客户提供终极帮助是多么容易和简单!

PS 本课程有 30 天全额退款政策 – 不问任何问题!

本课程适合谁:

  • 希望获得有关如何为软件产品用户提供帮助的实用知识的软件开发人员
  • 从事软件开发项目但现在努力为他们的应用程序创建文档交付的学生
  • 如果您从事技术作家、开发人员、架构师、经理或产品所有者的职业
  • 想要了解技术写作基础知识的业务分析师
  • 技术作家和信息开发人员