如何撰写技术博客

快速摘要

在这篇文章中，我将向你展示如何撰写技术文章。文章详细概述了技术文章的结构，提供了一些有用的示例，以及我从经验中总结出的一些重要技巧。

简介

软件开发人员开始写博客的原因之一是分享他们的技术知识和经验。有些人没有意识到，分享这些技术知识是他们在基本博客技能之外必须培养的一项技能。在这篇文章中，我将向你展示如何撰写技术文章。

技术岗位结构

技术文章的结构与普通博客文章不同。技术文章需要你向读者提供元信息，因为他们可能会决定实施你正在解释的内容。一般来说，技术文章的结构如下：

标题
快速摘要
要求
介绍
多步骤解释
示例
尖端
概括

让我解释一下它们分别是什么。

标题

技术文章的标题非常重要。它是内容的一部分，告诉读者如何做某事。这就是为什么很多技术标题都使用“如何做某事”这种写法。这种写法清晰、直接，并且避免使用任何令人困惑的术语（你最不想做的就是让读者感到困惑）。如果你还没注意到，这篇文章的标题就是这种方法的体现。

其他非常有用的标题类型如下：

Writing a $technology $thing.

Developing with $technology.

Testing $technology with $thing.

请注意，这里有一个非常简单的模式。实用的技术标题通常以动词开头，这些动词可以快速解释文章内容，而无需读者花费时间阅读。

快速摘要

快速摘要并非总是必要的，但大多数时候绝对有用。它用两三句话概括文章内容，节省读者的时间。可以把快速摘要想象成一种较长的副标题。标题和快速摘要之间保持联系很重要。标题结束的地方，快速摘要应该继续。阅读这篇文章的标题和快速摘要，看看它们的过渡是否流畅。

要求

要求是指读者为了顺利阅读和应用文章内容所需要具备的条件。如果您正在编写 Python 教程，那么要求包括：使用的 Python 版本、文本编辑器等等。请尽可能具体地说明版本信息。让我用上面的例子来演示如何操作：

要求：

Python 3.6.1

Text Editor (Vim was used for the examples)

Operating System (Linux, MacOS, Windows) with version information (Ubuntu 16, MacOS 10.12, Windows 10 Professional)

需求非常重要，因为软件版本和平台各不相同。清晰地说明你所使用的软件可以让读者了解他们是否具备跟进的能力。如果没有，他们可以在继续阅读之前做好准备。很多技术文章在这方面做得不好，导致读者不得不自己去解决问题。优秀的技术作家可以让读者避免这种挫败感。

介绍

引言部分解释了你的技术文章将涵盖哪些内容。它可以用来处理所有非技术性的内容。人们经常在引言中加入技术细节。这不是一个好主意，因为引言可能会很长，而且结构混乱。我讨厌人们在引言中加入晦涩难懂的技术细节，因为这会让我立刻感到困惑。以下是一个很好的引言示例：

Python has become the defacto glue language in software development. In it's newest version (3.6.1), the language has evolved into a powerful tool that is easy to pick up. Python is included as a default in most Linux distros, and in MacOS. Such widespread adoption means you will probably not need to install anything in order to run Python on your machine. Follow along as I explain how to use Python's F-Strings in a Linux environment.

请注意，介绍如何通过提供一些简单的背景信息来帮助您获得成功，但不包含以后需要的任何技术细节，并且这些细节之前并未在要求中概述。

多步骤解释

这是你详细解释事情的部分。我强调多步骤，因为将事情分解成更小的部分，可以让作者更容易理解，也让读者能够快速继续阅读。多步骤也有助于在读者心中构建良好的思维图像。

解释中每个步骤应该有多详细？尽可能详细。有时可能只有一句话。然而，篇幅不如范围重要。我们来稍微谈谈范围。

技术文章中的作用域与编程语言中的作用域相同。有局部作用域和全局作用域。全局作用域是指在某个地方讨论的信息适用于其他所有内容。局部作用域是指讨论的信息适用于你现在正在阅读的内容。

解释中的每个步骤都具有局部和全局范围。这意味着每个步骤中讨论的信息首先对该步骤本身很重要，其次才是对整个文章的重要性。但反之则不然。范围优先，而且非常重要。解释中任何部分的范围设置不当都会使读者感到困惑。

借助视觉提示，有多种方法可以局部地封装作用域。视觉提示是图形或排版元素，可以让读者知道特定区域内的所有内容都与其自身（局部作用域）密切相关，但与全局作用域关联不大。我来举个例子：

#######
#
# This is a globally encapsulated scope. 
# Note that everything that I write here is assumed to be directly related.
# 
# I wrote this post as a result of a Tweet!
#
######


######
#
# This is a locally encapsulated scope. What I write here is separate from the rest.
#
#  #####
#  #
#  # How are you enjoying this post?
#  #
#  #
#  # #####
#  # #
#  # # Yes, this totally looks like OOP. It is not a coincidence. :)
#  # #
#  # #####
#  # 
#  #####
#
######

我想让你注意的一点是，最深层的作用域仍然与其他两层相关，但在交流思想时具有优先性。人们倾向于先阅读最深层的作用域。这一点非常重要。人们在阅读作用域时遵循的顺序是先阅读最深层。以上面的例子为例，人们倾向于按照以下顺序阅读上面的文本：

First -> 是的，这看起来完全像 OOP。这不是巧合。:)
第二 -> 您喜欢这篇文章吗？
第三 -> 这是一个局部封装的作用域。我在这里写的内容与其他地方是分开的。

总而言之，将事情分解成更小的步骤，并提供视觉提示，让读者了解范围。保留与特定步骤局部相关的内容。如有疑问，请分解并提供视觉提示。最好有多个小步骤（微步骤），而不是一堆大步骤。

示例

如今，提供示例已是必需的。人们通常会跳过其他所有内容，直接查看示例。因此，在示例中重复所有内容至关重要。没错，这意味着要将需求和多个步骤的说明也包含在示例中。您无需将文本复制粘贴到示例中，而是提供更简洁的版本。

示例是技术文章中最重要的部分，因为人们会利用它们来理解你正在讨论的内容。事实上，人们对技术文章的反响与示例的质量直接相关。你提供的示例越多越好。但是，请确保提供不同长度和类型的示例。你当然不会忘记包含一个“Hello, World”示例，但也不要让它成为你唯一包含的示例。我将使用 Python 的 F 字符串向你展示一些可以借鉴的例子。

用作介绍的非常简单的示例：

# python 3.6.1 on MacOS 10.12

# Hello world with F-Strings

name = "World"
print(f"Hello, {name}")

展示一些特定技术细节（本地范围）的简单示例：

# python 3.6.1 on MacOS 10.12

# Using Python's F-Strings in functions

def hello(name):
    return f"Hello, {name}"

def print_hello(name):
    print(hello(name))

更复杂的例子是：

# python 3.6.1 on MacOS 10.12

# Implementing FizzBuzz with Python's F-Strings
# and ternary operators

def fizzbuzz():
  for i in range(1, 101):
      print(f"FizzBuzz with number {i}") if i % 3 == 0 and i % 5 == 0 else None
      print(f"Fizz with number {i}") if i % 3 == 0 else None
      print(f"Buzz with number {i}") if i % 5 == 0 else None
      print(f"Now on number {i}")

重点在于逐步提升示例的复杂度，从而引导用户完成学习之旅。以上每个示例都基于上一个示例，并共享一个主题：Python 的 F 字符串。

尖端

我决定分享一些这些年来学到的技巧。有些技巧并非总是适用，但了解一下还是很有用的。

如有疑问，请解释。多解释总是有益的。如果使用视觉提示来提供更深入的解释，就可以避免写长篇大论。通过用视觉提示将它们分开，如果人们很快就能理解，就可以避免阅读它们。
避免使用低对比度的颜色作为视觉提示。深灰色背景上浅灰色字体效果不佳。务必确保字体易于阅读。
让多人阅读。反馈很重要。反馈就像大多数人都能理解的东西和让所有人都感到困惑的东西之间的区别。由于技术文章的性质，很容易写出令人困惑的文章。
KISS。保持简单，傻瓜。少量细节就能说明一切，就别塞进一堆细节。
学习备受赞誉的技术帖子或文档。人们喜欢称赞 Stripe 的文档。找出原因，并将学到的知识运用到你的帖子中。
使用图形来分解文本。我通常坚持尽可能少用图形，但它们可能很有用。这取决于讨论的内容。大多数情况下，你需要自己绘制图形。不要画得太花哨。尽量使用 2-5 种颜色，并保持简洁。
不要将源代码放在图形或图像中。人们喜欢将代码复制并粘贴到他们的编辑器中。
允许他们在文章中运行代码。这并不总是可行的，但有时很有用。
尽可能使用锚文本。人们通常会收藏你的页面。在文章的特定区域添加锚文本，可以让他们在阅读结束的地方添加书签。例如，示例很有用。
语气轻松最好。幽默没什么用。尽量使用轻松的笑话，并且不要在源代码中提及。

概括

摘要用于添加指向附加信息的链接、感谢帮助撰写文章的人，以及添加任何可能对读者有用的内容。我喜欢使用以下格式：

You have now learned about Python's F-Strings. If you'd like to learn more about them, please visit the following links:

- Pep 498, https://www.python.org/dev/peps/pep-0498/

I must thank all of the people who made this post possible. If you need Python development services, please visit yelluw.com and use the contact form to get in touch with me. Feel free to email me at pryelluw@gmail.com with questions.

上面的格式将与文章相关的重要链接放在最前面，所有手续放在第二位，联系方式放在第三位。我总是把联系方式放在最后，因为人们往往会在那里寻找。

现在你已经学会了如何撰写技术博客文章。这非常有用，因为公司倾向于聘请能够
清晰沟通的软件开发人员。这也可以成为一种补充收入的方式。我必须感谢 Stephanie Hurlburt 提供的想法和支持。在 Twitter 上关注她@sehurlburt，她很棒。

如果您需要撰写技术文章，请随时通过Yelluw 的网站联系我。您也可以发送电子邮件至pryelluw@gmail.com。您还可以关注 Yelluw 的 Twitter 账号@yelluwmedia和我的个人账号@pryelluw。我也可以签订短期和长期软件开发合同。我目前专注于 Python、Django 和 Javascript。

文章来源：https://dev.to/yelluw/how-to-do-technical-blogging