《技术写作入门指南》和原文 Technical Writing for Beginners – An A-Z Guide to Tech Blogging Basics 均来自于非营利性编程社区 freeCodeCamp，作者 Amarachi Emmanuela Azubuike 是一名前端 Web 开发人员，因此其技术写作内容和其他众多的主题文章一样特定于编程工作。您更可以将其基本思路应用于更多的领域。
如果您喜欢写作和技术，技术写作可能是一个适合您的职业。如果您喜欢技术，但又不喜欢整天编程，您也可以做这个工作。
如果您喜欢通过教别人学习，为开源项目做贡献并教别人如何做，或者基本上喜欢通过写作以简单的方式解释复杂的概念，技术写作也可能适合您。
让我们深入了解基本原理，了解在开始技术写作时您应该知道和考虑什么。
目录
在这篇文章中，我们将关注：
- 技术写作是什么
- 技术写作的益处
- 作为一个技术作家所必须具备的技能
- 技术写作流程
- 发布文章的平台
- 技术写作课
- 技术写作论坛和社区
- 一些值得关注的技术作家
- 结束语和参考资料
技术写作是什么
技术写作是一门提供以细节为导向的指导的艺术，以帮助用户了解特定的技能或产品。
而技术作家就是写这些说明的人，也就是所谓的技术文档或教程。这可能包括用户手册、在线支持文章或编码员/API开发人员的内部文档。
技术作家的沟通方式是介绍技术信息，使读者能够理解这些信息。
技术写作的益处
技术作家是终身学习者。由于这项工作涉及以简单明了的方式传达复杂的概念，您必须精通您所写的领域，或者愿意学习相关知识。
这很好，因为您每研究和编写一份新的技术文件，您就会成为该领域的专家。
技术写作也让您对用户有更好的同理心。它帮助您更多地关注产品的读者或用户的感受，而不是您的想法。
作为一名技术作家，您也可以通过向组织投稿来赚钱。这里有一些付钱给您为他们写作的组织，像Smashing Magazine、AuthO, Twilio、和 Stack Overflow.
除了这些，您还可以为开源社区做出贡献，并参与付费的开源项目， 像Google Season of Docs 和Outreachy。
您也可以把技术写作作为一个全职职业——很多公司都需要具备这些技能的人。
作为一个技术作家所必须具备的技能
理解英语的正确使用
在您考虑写作之前，有必要对英语的时态、拼写和基本语法有良好的掌握。您的读者不希望读到一篇充斥着不正确的语法和糟糕的选词的文章。
知道如何清楚和简单地解释事情
知道如何实现一个功能，并不一定意味着您能清楚地把这个过程传达给别人。
为了成为一名好老师，您必须有同理心，有能力以适合您的目标受众的方式教授或解释术语。
如果您不能向一个六岁的孩子解释，那么您自己也不了解它。——阿尔伯特·爱因斯坦
具备一定的写作能力
我相信作家是后天培养的，不是天生的。您只能通过实际写作来学习如何写作。
在您将笔放在纸上之前，您可能永远不会知道自己是否有写作能力。只有一种方法可以知道您是否有一些写作技巧，那就是写作。
所以我鼓励您今天开始写作。您可以选择从我在本节中列出的任何平台开始，以伸展您的写作能力。
当然，有一些技术领域的经验也是一个巨大的好处。
技术写作流程
分析和了解谁是您的读者
当您写一篇技术文章时，需要考虑的最大因素是您的目标/预期受众。它应该始终处于您头脑的最先考虑的。
一个好的技术作家是根据读者的情况来写作的。例如，假设您正在写一篇针对初学者的文章，重要的是，不要假设他们已经知道某些概念。
您可以在文章的开头概述任何必要的先决条件。这将确保您的读者在直接进入您的文章之前拥有（或能够获得）他们需要的知识。
您还可以包括有用的资源链接，这样您的读者只需点击一下就能获得他们需要的信息。
为了知道您是为谁写的，您必须尽可能多地收集关于谁将使用该文件的信息。
重要的是要知道您的听众是否有该领域的专业知识，该主题对他们来说是否完全陌生，或者他们是否介于两者之间（有一些了解）。
您的读者也会有他们自己的期望和需求。您必须确定当读者开始阅读文件时，他们在寻找什么，以及他们将从文件中得到什么。
为了了解您的读者，在您开始写作之前，问自己以下问题：
- 谁是我的读者？
- 他们需要什么？
- 他们将在哪里阅读？
- 他们何时阅读？
- 他们为什么要阅读？
- 他们将如何阅读？
这些问题也有助于您思考读者在阅读您的文章时的体验，我们现在会更多地讨论这个问题。
思考用户体验
用户体验在技术文档中与在网络上的任何地方一样重要。
现在您知道了您的听众和他们的需求，请牢记文件本身是如何满足他们的需求的。否则很容易写出忽略读者如何实际使用文档。
在您写作的时候，不断地退后一步，把您当作读者来看待这个文档。问问自己。它是无障碍的吗？您的读者将如何使用它？他们什么时候使用它？它容易浏览吗？
我们的目标是写一份对您的读者有用和可使用的文件。
规划您的文档
牢记您的用户是谁，然后您就可以构思和规划您的文件了。
这个过程包括一些步骤，我们现在就来看看。
对主题进行彻底研究
在规划您的文档时，您必须研究您要写的主题。只要在谷歌上搜索，就有大量的资源供您使用，并从中获得更深的见解。
不要被诱惑去抄袭别人的作品或文章，并把它当作您自己的作品，因为这是剽窃行为。相反，将这些资源作为您工作的参考和想法。
尽可能多地使用谷歌，从研究期刊、书籍或新闻中获取事实和数据，并尽可能多地收集有关您的主题的信息。然后您就可以开始制定大纲了
制定大纲
在扩展您的文档内容之前，先列出大纲，有助于您以更集中的方式写作。它还可以让您组织您的思想，实现您的写作目标。
大纲还可以帮助您确定您希望读者从文件中得到什么。最后，它为完成您的写作确立了一个时间表。
获取相关的图形/图片
有一个大纲非常有助于确定您需要在文档的不同部分嵌入的各种虚拟辅助工具（信息图表、gif、视频、推文）。
而且，如果您把这些相关的图形放在手边，会使您的写作过程更加容易。
用正确的风格写作
最后，您可以开始写作了！如果您已经完成了所有这些步骤，写作应该变得容易得多。但是您仍然需要确保您的写作风格适合技术文件。
写作需要易懂、直接和专业。花哨或情绪化的文字在技术文件中是不受欢迎的。为了帮助您保持这种风格，这里有一些您应该培养的关键特征。
使用主动语态
在您的文章中使用主动语态是个好主意，因为它比被动语态更容易阅读和理解。
主动语态意味着句子的主语是主动执行动词的动作的人。被动语态是指，主语是动词动作的接受者。
下面是一个被动语态的例子：这文档应该被网络开发人员每年阅读六次。
这里有一个主动语态的例子：每个网络开发人员都应该每年读6次这个文档。
谨慎地选词
选词很重要。确保您使用最适合上下文的词。避免过度使用代词，如“它”和“这个”，因为读者可能难以识别它们指的是哪个名词。
还要避免俚语和粗俗的语言——记住您是在为更多的读者写作，他们的性情和文化风俗可能与您不同。
避免过多的专业术语
如果您是您所在领域的专家，很容易使用您熟悉的行话，而没有意识到它可能会让其他读者感到困惑。
您也应该避免使用您以前没有解释过的缩略语。
下面是一个例子：
不清晰：PWAs确实被认为是多平台开发的未来。它们在安卓和iOS上的可用性使它们成为未来的应用程序。
改进版：Progressive Web Applications（PWAs） 是真正的多平台开发的未来。它们在Android和iOS上的可用性使PWAs成为未来的应用程序。
使用通俗易懂的说法
尽量简短说明，以任何读者都能理解的方式来写。 避免使用大量冗长的字。始终尝试以最清晰的方式解释概念和术语。
视觉上的可视化
大量文字是很难阅读的。即使是最清晰的指示也会在视觉效果不佳的文件中消失。
他们说，一张图片胜过千言万语。这在技术写作中也是正确的。
但是，并不是任何图片都值得在技术文件中使用。技术信息可能很难仅仅通过文字来传达。放置得当的图片或图表可以阐明您的解释。
人们也喜欢视觉效果，因此将它们插入正确的位置很有帮助。考虑下面的图片：
首先，这里有一个没有视觉效果的博客片段：
step2-1
以下是同一博客的一个片段，但有视觉效果：
step1-1
在您的文章中添加图片，使内容更有亲和力，更容易理解。除了图片，您还可以在必要时使用gif、emoji、embeds（社交媒体、代码）和代码片段。
深思熟虑的格式、模板和图像或图表也会使您的文本对读者更有帮助。您可以查看下面的参考资料，了解@Bolajiayodeji的技术写作模板。
仔细检查
任何类型的好文章都必须没有拼写和语法错误。这些错误可能看起来很明显，但并不总是容易发现它们（尤其是在长篇文件中）。
在点击 "发布 "之前，一定要仔细检查您的拼写（您知道，点您的Is和交叉您的Ts，从英文的角度来讲，I与T，看起来挺近似的，注意拼写错误）。
有许多免费的工具，如Grammarly和Hemingway app，您可以用它们来检查语法和拼写错误。您也可以把您的文章草稿与别人分享，以便在发表前进行校对。
发布文章的平台
既然您已经决定从事技术写作，这里有一些好的平台，您可以开始免费发布技术内容。它们还可以帮助您建立一个有吸引力的作品集，供未来的雇主查看。
Dev.to是一个由成千上万的技术人员组成的社区，作者和读者都可以有意义地参与并分享想法和资源。
devto
Hashnode是我的首选博客平台，它有令人羡慕的福利，如自定义域名映射和互动社区。在这个平台上建立一个博客也很容易和快速。
hashnode
freeCodeCamp 有一个非常大的社区和受众范围，是一个发表文章的好地方。然而，您需要申请为他们的专栏写作，并提供一些以前写的文章。
您的申请可能被接受或拒绝，但不要灰心。您总是可以在以后变得更好时重新申请，谁知道呢？您可能会被接受。
如果您真的为他们写作，他们会在发表前审查和编辑您的文章，以确保您发表最精炼的文章。他们还将在其社交媒体平台上分享您的文章，以帮助更多的人阅读它们。
freecodecamp
Hackernoon 有超过7000名作家，可能是一个伟大的平台，让您开始向社区中每天超过20万的读者发布您的文章。
Hacker Noon为作家提供帮助，在他们的文章在平台上发布之前进行校对，帮助他们避免常见错误。
hackernoon
技术写作课
就像其他领域一样，技术写作也有各种流程、规则、最佳实践等等。
参加技术写作课程将有助于指导您完成您需要学习的每一件事，也可以给您一个重大的信心提升，以启动您的写作之旅。
以下是一些技术写作课程，您可以去看看：
- 谷歌技术写作课程（免费）
- Udemy技术写作课程（收费）
技术写作论坛和社区
独自一人，我们能做的太少，一起努力，我们能做的太多。——海伦 凯勒
成为社区或论坛的一部分，与那些与您有同样激情的人在一起是有益的。您可以从社区中的其他作家那里得到反馈、纠正、提示，甚至学习一些写作风格提示。
这里有一些社区和论坛供您加入：
- 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上快速建立您的博客并开始写作。
您通过写作以及阅读和思考别的写作者如何创作人物和故事来学习写作。如果您不是一个读者，就别想成为一个写作者。——Jean M. Auel
技术作家总是在学习。通过潜心研究新的主题领域和接受外部反馈，一个好的作家永远不会停止磨练自己的技艺。
当然，好的作家也是贪婪的读者。通过回顾深入阅读或频繁使用的文档，您自己的写作肯定会提高。
我非常期待看到您的技术文章！
还不快抢沙发