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