初学者的技术写作：技术博客基础知识A-Z指南

 

如果你喜欢写作和技术，技术写作可能是一个适合你的职业。如果你喜欢技术，但又不是真的整天喜欢编码，也可以做一些别的事情。

如果你喜欢通过教导他人来学习，为开源项目做出贡献，并教导他人如何做到这一点，或者基本上喜欢通过你的写作以简单的方式解释复杂的概念，技术写作也可能适合你。

让我们深入了解基础知识，了解你在开始技术写作时应该知道和考虑的问题。

目录

 

什么是技术写作？

技术写作的好处

作为技术作家必须具备的技能

了解正确的英语用法

知道如何清楚、简单地解释事物

具备一定的写作技巧 ‌‌

技术写作过程

分析并了解你的读者是谁

考虑用户体验

计划你的文档

对该主题进行深入研究

做一个大纲

获取相关的图形/图像

以正确的风格写作

在哪里发表文章

国内

国外

技术写作课程

技术写作论坛和社区

下面是一些令人惊叹的技术作家

最后的话

参考资料

---

什么是技术写作？

技术写作是一门艺术，提供细节导向的指导，以帮助用户理解特定的技能或产品。

技术作者是写这些说明的人，也称为技术文档或教程。这可能包括用户手册、在线支持文章或者程序员/API 开发者的内部文档。

技术写作者的交流方式是将技术信息呈现给读者，使读者能够将这些信息用于预期的目的。

技术写作的好处

技术写作者也是是终身学习者。由于这份工作需要用简单而直接的术语来表达复杂的概念，所以你必须精通你所写的领域，或者愿意学习它。

这很好，因为每研究和编写一份新的技术文档，你就会成为该领域的专家。

技术写作还能让你更好地理解用户的感受，它帮助你更多地关注读者或用户对产品的感受，而不是你的想法。

你也可以通过为组织撰稿来赚钱。下面是一些付钱给你为他们写文章的机构，比如Smashing 杂志、AuthO、Twilio和Stack Overflow。

除此以外，你还可以为开源社区做贡献，参与 Google Season of Docs 和 Outreachy 等付费开源项目。

你也可以把技术写作作为一个全职职业——很多公司都需要有这些技能的人。

作为技术作家必须具备的技能

了解正确的英语用法

在你考虑写作之前，有必要掌握好英语、时态、拼写和基本语法。你的读者不希望读到一篇充满错误语法和糟糕词汇选择的文章。

知道如何清楚、简单地解释事物

知道如何实现功能并不一定意味着你可以与其他人清楚地交流该过程。

为了成为一名优秀的老师，你必须具有同理心，能够以适合你的目标受众的方式教授或描述术语。

如果你不能向六岁的孩子解释它，那么你自己也不了解。——艾尔伯特·爱因斯坦

具备一定的写作技巧 ‌‌

我相信，作家是天生的，而不是后天的，而你只有通过实际写作才能学会如何写作。

你可能永远都不知道你有写作的能力，直到你把笔放到纸上。而要想知道自己是否有一定的写作能力，只有一个办法，那就是通过写作。

所以我鼓励你从今天开始写作。你可以选择从我在本节中列出的任何一个平台开始，以扩展你的写作能力。

当然，拥有一些技术领域的经验也是巨大的好处。

技术写作过程

分析并了解你的读者是谁

当你在写一篇技术文章时，要考虑的最大因素是你的预期/期望受众。它应该始终在你的脑海中占据最重要的位置。

一个好的技术写作者会根据读者的语境来写作。举个例子，比如说你要写一篇针对初学者的文章。重要的是，不要假设他们已经知道某些概念。

你可以在文章开头概述任何必要的先决条件。这将确保你的读者在直接进入你的文章之前已经（或能够获得）他们所需要的知识。

你还可以加入有用资源的链接，这样你的读者只需点击一下就能获得他们需要的信息。

为了知道你是为谁而写，你必须尽可能多地收集关于谁将使用该文件的信息。

重要的是要知道你的读者是否在该领域有专业知识，是否这个话题对他们来说是全新的，或者他们是否介于两者之间。

你的读者也会有他们自己的期望和需求。当读者开始阅读文档时，你必须确定他们在寻找什么，以及他们将从中获得什么。

要了解你的读者，请在开始写作之前先问自己以下几个问题：

• 我的读者是谁？
• 他们需要什么？
• 他们将在哪里阅读？
• 他们什么时候阅读？
• 他们为什么要阅读？
• 他们将如何阅读？

这些问题还能帮助你思考读者在阅读你的写作时的体验，这一点我们现在要多说几句。

考虑用户体验

用户体验在技术文档中和在网络上的任何地方一样重要。

既然你知道了你的受众和他们的需求，就要记住文档本身是如何为他们的需求服务的。很容易忽略读者实际会如何使用文档。

写作时，不断后退一步，把自己当成读者来看待文档。问问自己： 它是可访问的吗？你的读者将如何使用它？他们何时会使用它？是否易于阅读？

目的是编写一个对读者有用和可用的文档。

计划你的文档

记住你的用户是谁，然后你就可以对你的文档进行构思和规划。

这个过程包括许多步骤，我们现在将继续进行。

对该主题进行深入研究

在规划你的文档时，你必须研究你要写的主题。有大量的资源只需在谷歌上搜索一下就可以供你消费，并从中获得更深的见解。

不要试图从别人的作品或文章中摘录下来，然后当作自己的作品，因为这就是抄袭。相反，将这些资源作为你工作的参考和想法。

尽可能多地使用谷歌，从研究期刊、书籍或新闻中获取事实和数据，尽可能多地收集有关你的主题的信息。然后你就可以开始做一个大纲了。

做一个大纲

在扩展文档内容之前先列出提纲，这有助于你更专注地写作。它还可以让你组织你的思路，实现你的写作目标。

提纲还可以帮助你确定你希望读者从文档中得到什么。最后，它为你的写作建立了一个时间表。

获取相关的图形/图像

在确定需要嵌入到文档不同部分的各种虚拟辅助工具(信息图、gif、视频、tweet)时，有一个大纲非常有用。

如果你把这些相关的图形放在手边，会让你的写作过程变得更加轻松。

以正确的风格写作

终于，你可以开始写作了！如果你已经完成了所有这些步骤，写作应该会变得容易很多。但你仍然需要确保你的写作风格适合技术文档。

写作需要通俗易懂、直接和专业，在技术文档中不欢迎花哨或情绪化的文本。为了帮助你保持这种风格，这里有一些你应该培养的关键品质。

使用主动语态

在文章中使用主动语态是个好主意，因为它比被动语态更容易阅读和理解。

主动语态是指句子的主语是主动执行动词动作的人，被动语态是指主语是动词动作的接受者。

这是一个被动语态的示例：每个 Web 开发人员每年应阅读六次文档。

下面是一个主动语态的例子：每个 web 开发人员一年应该阅读该文档 6 次。

慎重选择你的词汇

词语选择很重要，确保你使用最适合上下文的词汇。避免过度使用代词，如“它”和“这”，因为读者可能难以识别它们指的是哪个名词。

还要避免使用俚语和粗俗的语言——请记住，你是在为更多的读者写作，他们的性格和文化倾向可能与你不同。

避免过多的行话

如果你是你所在领域的专家，很容易使用你熟悉的行话，而没有意识到它可能会让其他读者感到困惑。

你还应该避免使用以前没有解释过的首字母缩写词，这是一个例子：

不太清楚的是：PWAs真正被认为是多平台开发的未来。它们在 Android 和 iOS 上的可用性使其成为未来的应用。

改进：渐进式网络应用（PWA）是真正的多平台开发的未来。它们在 Android 和 iOS 上的可用性使 PWA 成为未来的应用。

使用简单的语言

避免使用冗长的大词，总是尽量以最清晰的方式解释概念和术语。

可视化格式化

一堆文字很难读懂，即使是最清晰的指令也可能在视觉表现不佳的文档中丢失。

他们说，一张图片胜过千言万语，即使在技术写作中也是如此。

但是，并非任何图像都可以配上，仅用文本表达技术信息是困难的，放置恰当的图像或图表可以澄清你的解释。

人们也喜欢视觉效果，所以把它们插入到正确的位置是有帮助的。看看下面的图片：

首先，这是一个没有视觉效果的博客片段：

这是同一博客的片段，但带有视觉效果：

在你的文章中添加图片，可以使内容更加贴切，更容易理解。除了图片，你还可以在必要时使用 gif、表情、嵌入（社交媒体、代码）和代码片段。

贴心的格式、模板和图片或图表也会让你的文字对读者更有帮助。

仔细检查

任何类型的好文章都必须没有拼写和语法错误。这些错误可能看起来很明显，但并不总是很容易发现它们（特别是在长篇文章中）。在点击“发布”之前，一定要仔细检查你的拼写。

有许多免费的工具，如Grammarly和Hemingway app，你可以用来检查语法和拼写错误。你也可以在发表前与别人分享你的文章草稿，让他校对。

在哪里发表文章

既然你已经决定开始从事技术写作，这里有一些不错的平台，你可以在那里免费发布技术内容。他们还可以帮助你建立一个吸引未来雇主的投资组合。

国内

Segmentfault 思否是中国领先的新一代开发者社区和专业的技术媒体，笔者主力发文平台之一。

掘金 是一个帮助开发者成长的社区，特别是前端技术，现在已经是整个行业里最活跃的，笔者主力发文平台之一。

CSDN 是全球知名中文 IT 技术交流平台,创建于 1999 年，包含原创博客、精品问答、职业培训、技术论坛、资源下载等产品服务，提供原创、优质、完整内容的专业 IT 技术开发社区。

知乎 有问题，上知乎。是中文互联网知名的可信赖问答社区，致力于构建一个人人都可以便捷接入的知识分享网络，让人们便捷地与世界分享知识、经验和见解，发现更大的世界。

国外

Dev.to是一个由数千名技术爱好者组成的社区，在这里，作者和读者都可以有意义地参与并分享想法和资源。

Hashnode是我常用的博客平台，它有很多好处，比如自定义域名映射和互动社区。在这个平台上设置博客也很简单快速。

freeCodeCamp有一个非常大的社区和受众，是一个发布你的文章的好地方。但是，你需要使用一些以前的写作示例来申请为他们的出版物写作。

你的申请可能被接受，也可能被拒绝，但不要灰心。你总是可以在以后重新申请，因为你变得更好，谁知道呢？你可能会被录取。

如果你真的为他们写文章，他们会在发布前审核和编辑你的文章，以确保你发布的文章是最精致的。他们还会将你的文章分享到他们的社交媒体平台上，帮助更多的人阅读。

Hackernoon拥有超过 7,000 名作家，可以成为一个很好的平台，让你开始向社区中每天超过 20 万的读者发布你的文章。

Hacker Noon 支持作者在平台上发布文章前对其进行校对，帮助他们避免常见错误。

技术写作课程

就像其他领域一样，技术写作也有各种流程、规则、最佳实践等。

参加技术写作的课程会帮助你完成你需要学习的每一件事，也可以给你很大的信心，开启你的写作之旅。

你可以查看以下一些技术写作课程：

• Google 技术写作课程（免费）
• Udemy 技术写作课程（付费）
• Hashnode 技术写作训练营（免费）

技术写作论坛和社区

独自一人，我们可以做得很少，但一起，我们可以做得很多——海伦·凯勒。

成为一个社区或论坛的一部分，与那些和你有同样热情的人一起是有益的。你可以得到反馈、纠正、技巧，甚至从社区中的其他作家那里学习一些风格技巧。

以下是一些社区和论坛供你加入：

• Hashnode
• Dev.to
• Technical Writing World
• Technical Writer Forum
• Write the Docs Forum

下面是一些令人惊叹的技术作家

在我的技术写作之旅中，我跟随了一些伟大的技术作家，他们的写作之旅、一致性和风格都激励着我。

这些都是我仰望的作家，他们被我视为技术写作的虚拟导师。有时，他们会给我一些技术写作技巧，我觉得很有帮助，也从他们那里学到了很多东西。

以下是其中一些作家（与他们的 Twitter 超链接）：

• Quincy Larson
• Edidiong Asikpo
• Catalin Pit
• Victoria Lo
• Bolaji Ayodeji
• Amruta Ranade
• Chris Bongers
• Colby Fayock

最后的话

你不需要技术写作的学位就可以开始发布技术内容。你可以开始在你的个人博客和公共 GitHub 知识库上写作，同时构建你的作品集并获得实践经验。

真的——开始写吧。

通过为现有程序或项目创建新的文档来练习。GitHub 上有很多开源项目，你可以查看并添加到他们的文档中。

有没有一个你喜欢使用的应用程序，但是它的文档写得很糟糕？写下你自己的，并在网上分享以获得反馈。你还可以在 hashnode 上快速设置博客并开始写作。

技术作家一直在学习。通过深入到新的主题领域，并接受外部反馈，一个优秀的作家永远不会停止磨练自己的技艺。

当然，优秀的作家也是贪婪的读者。通过检查大量阅读和使用的文档，你的写作能力肯定会得到提高。

等不及要看你的技术文章了！

参考资料

Introduction to Technical Writing‌‌

How to structure a technical article‌‌

Understanding your audience, the why and how

‌‌Technical Writing template

我希望这可以帮到你。

---

原文：https://blog.zhangbing.site/2020/11/29/technical-writing-for-beginners/

来源：https://www.freecodecamp.org/news/technical-writing-for-beginners/