关于程序员:初学者的技术写作技术博客基础知识AZ指南

如果你喜爱写作和技术，技术写作可能是一个适宜你的职业。如果你喜爱技术，但又不是真的终日喜爱编码，也能够做一些别的事件。

如果你喜爱通过教诲别人来学习，为开源我的项目做出奉献，并教诲别人如何做到这一点，或者基本上喜爱通过你的写作以简略的形式解释简单的概念，技术写作也可能适宜你。

让咱们深刻理解基础知识，理解你在开始技术写作时应该晓得和思考的问题。

什么是技术写作？

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

技术作者是写这些阐明的人，也称为技术文档或教程。这可能包含用户手册、在线反对文章或者程序员 /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

我心愿这能够帮到你。