技术博客文章中应包含的 7 条信息

[图片：#WOCinTech 聊天]

我真正想知道的是：“技术博客文章中缺少什么？” 我经常被问到技术博客文章应该包含哪些信息，以及文章应该如何组织。作为一名技术内容的读者，我有时只有在阅读之后才意识到缺少了什么。我想知道其他人是否能够识别出他们在博客中需要的信息，以及原因。（我收到了 22 条回复；感谢所有在帖子中分享想法的人！）

在这篇文章中，我将根据 Twitter 上开发人员的反馈，分享技术博客文章中应包含的七个关键信息：

1. 介绍和阐释代码片段的文本

代码片段前的文字能够有效地引导读者。如果没有任何上下文或说明，读者可能会感觉错过了某个步骤，无法理解作者是如何得出这些内容的。如果没有明确的信息，读者可能会产生以下疑问：

我在看什么？
这是命令行还是文件？
我是否应该在某处输入这个内容，或者这是其他地方的输出？
预期的输出/行为是什么？
我输入这段代码时出现错误。我应该收到错误信息吗？

如何编写优秀的代码片段？DigitalOcean 的编写指南包含一个名为“命令和代码分步讲解”的部分，其中包含如何格式化命令和代码片段以及如何引入它们的示例。Redux维护者 Mark Erikson还建议在文件顶部包含路径和文件名。

2. 代码片段作为文本

有些博客允许作者保留代码块的格式，但有些博客则不允许。作者通过将代码片段粘贴为屏幕截图来规避这种情况，但有一个问题：屏幕截图无法通过屏幕阅读器访问。不仅无法访问图片中的代码，而且作者也未始终如一地为图片添加替代文本。

为了使其可访问，请将代码片段托管在其他地方（例如 GitHub repo 或 gist），并在图像标题中添加代码片段的链接以供快速参考。

3. 所有图片、截图和图表的替代文本

继续讨论可访问性，替代文本 (alt text) 是一个 HTML 属性，作者可以在其中为图片添加描述。当屏幕阅读器在页面上找到图片时，它会读取替代文本中提供的所有描述。如果没有替代文本，屏幕阅读器就无法理解图片的含义。

今年早些时候，我建议在替代文本中添加代码片段。但Eric Eggert 建议将代码片段托管在其他地方，而不是将其放在替代文本中。不过，除了提供指向代码片段的链接外，还应在替代文本中添加代码片段的基本描述，以便屏幕阅读器使用。

4. 本教程代码的最终结果

最后应该是什么样子的呢？软件工程师 Thalida Noel 建议添加一篇教程博客文章中引用的代码的最终结果，以便“看看所有部分是如何组合在一起的，以确定这是否是我想要的实现方式。”

5. 先决条件，包括依赖项和库的列表

先决条件是读者在阅读您的博客文章之前需要了解、拥有或完成的事项的列表。例如，在食谱中，先决条件可能是原料和设备的列表，以及一些需要完成的准备工作。在技术博客文章中，先决条件应该列出读者需要具备的与某个主题相关的知识或经验，以及为了理解代码片段需要安装的所有依赖项和库。（Jacque Schrag 说，她曾在博客文章正文中看到过依赖项引用，但在先决条件中没有看到。）

6. 发布版本

由于软件版本控制，大多数技术教程都有保质期。在博客文章中包含发布版本可以帮助读者更轻松地找到这些信息；也许他们正在搜索使用 Ruby 2.2.6 而不是 Ruby 2.3 的博客文章。开发人员 Jorge Vergara 在其博客文章顶部将发布版本作为元数据列出。

7. 发布日期

正如@marmalade指出的那样，博客文章发布日期（或“上次更新”日期）是重要的元数据，它表明了博客文章中示例的时效性。如果没有它，读者就无法确定自己阅读的内容是否已过时（参见上文第6点）。请添加原始发布日期，如果文章已更新，也请添加“上次更新”日期，以表明信息是最新的。

虽然并不全面，但包括这七条信息将帮助您预测读者访问您的博客文章时可能提出的问题。

资源：

这篇文章最初发表在我的博客上

我是 Stephanie，一名内容策略师和技术项目经理。访问developersguidetocontent.com了解更多关于我的工作！

文章来源：https://dev.to/radiomorillo/7-pieces-of-information-to-include-in-technical-blog-posts-5go4